From 6d5f88c9e028a35ea28002b7fb160c06375e787a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 10 Mar 2026 14:08:33 -0500 Subject: [PATCH] chore: add hosted influxdb-docs MCP server to .mcp.json (#6914) * chore: add hosted influxdb-docs MCP server to .mcp.json Add the hosted InfluxDB documentation search MCP server (influxdb-docs.mcp.kapa.ai) as the primary MCP server using SSE transport. Keep the local server with a note that it uses deprecated endpoints. https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc * chore: add API key auth option for hosted influxdb-docs MCP server Make the API key-authenticated server the primary entry (influxdb-docs) using Bearer token from DOCS_KAPA_API_KEY env var. Keep the OAuth fallback as influxdb-docs-oauth for users without an API key. https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc * chore: rename env vars to INFLUXDATA_DOCS_ namespace Rename DOCS_KAPA_API_KEY, DOCS_API_KEY_FILE, DOCS_MODE, and MCP_LOG_LEVEL to use the INFLUXDATA_DOCS_ prefix for consistency. https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc * docs: add MCP server setup docs for contributors and AI agents Update CLAUDE.md, AGENTS.md, and content-editing SKILL.md with concise documentation for the hosted influxdb-docs MCP server, covering both API key and OAuth authentication options. https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc * fix: remove cross-agent references from .claude files and AGENTS.md Keep .claude/ files focused on Claude Code. Link AGENTS.md to the published MCP server docs page instead of mentioning tool-specific setup. https://claude.ai/code/session_01SURpmrJ2sxzBtp4euiAxpc --------- Co-authored-by: Claude --- .claude/skills/content-editing/SKILL.md | 42 +++---------- .mcp.json | 25 ++++++-- AGENTS.md | 78 +++++++++++++++++++++++++ CLAUDE.md | 10 ++++ 4 files changed, 115 insertions(+), 40 deletions(-) diff --git a/.claude/skills/content-editing/SKILL.md b/.claude/skills/content-editing/SKILL.md index eb35f23e6..863b5c101 100644 --- a/.claude/skills/content-editing/SKILL.md +++ b/.claude/skills/content-editing/SKILL.md @@ -359,33 +359,12 @@ Use the Documentation MCP Server when the information here is inconclusive, when ### Setup -The documentation MCP server is hosted—no local installation required. Add the server URL to your AI assistant's MCP configuration. +The documentation MCP server is hosted at `https://influxdb-docs.mcp.kapa.ai`—no local installation required. -**MCP server URL:** +Already configured in [`.mcp.json`](/.mcp.json). Two server entries are available: -```text -https://influxdb-docs.mcp.kapa.ai -``` - -**Claude Desktop configuration** (Settings > Developer): - -```json -{ - "mcpServers": { - "influxdb-docs": { - "url": "https://influxdb-docs.mcp.kapa.ai" - } - } -} -``` - -For other AI assistants see the [InfluxDB documentation MCP server guide](/influxdb3/core/admin/mcp-server/) -and verify the MCP configuration options and syntax for a specific AI assistant. - -**Rate limits** (per Google OAuth user): - -- 40 requests per hour -- 200 requests per day +- **`influxdb-docs`** (API key) — Set `INFLUXDATA_DOCS_KAPA_API_KEY` env var. 60 req/min. +- **`influxdb-docs-oauth`** (OAuth) — No setup. Authenticates via Google on first use. 40 req/hr, 200 req/day. ### Available Tool @@ -552,17 +531,12 @@ touch content/influxdb3/enterprise/path/to/file.md ### MCP Server Not Responding -The hosted MCP server (`https://influxdb-docs.mcp.kapa.ai`) requires: - -1. **Google OAuth authentication** - On first use, sign in with Google -2. **Rate limits** - 40 requests/hour, 200 requests/day per user - **Troubleshooting steps:** -- Verify your AI assistant has the MCP server URL configured correctly -- Check if you've exceeded rate limits (wait an hour or until the next day) -- Try re-authenticating by clearing your OAuth session -- Ensure your network allows connections to `*.kapa.ai` +- **API key auth** (`influxdb-docs`): Verify `INFLUXDATA_DOCS_KAPA_API_KEY` is set. Rate limit: 60 req/min. +- **OAuth auth** (`influxdb-docs-oauth`): Sign in with Google on first use. Rate limits: 40 req/hr, 200 req/day. +- Verify your network allows connections to `*.kapa.ai` +- Check if you've exceeded rate limits (wait and retry) ### Cypress Tests Fail diff --git a/.mcp.json b/.mcp.json index f600dfa67..f53854090 100644 --- a/.mcp.json +++ b/.mcp.json @@ -1,20 +1,33 @@ { "$schema": "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/refs/heads/main/schema/2025-06-18/schema.json", - "description": "InfluxData documentation assistance via MCP server - Node.js execution", + "description": "InfluxData documentation assistance via MCP servers", "mcpServers": { + "influxdb-docs": { + "comment": "Hosted InfluxDB documentation search. Uses API key auth (set INFLUXDATA_DOCS_KAPA_API_KEY env var). Get your key from the Kapa dashboard. Rate limits: 60 req/min.", + "type": "sse", + "url": "https://influxdb-docs.mcp.kapa.ai", + "headers": { + "Authorization": "Bearer ${INFLUXDATA_DOCS_KAPA_API_KEY}" + } + }, + "influxdb-docs-oauth": { + "comment": "Hosted InfluxDB documentation search (OAuth). No API key needed--authenticates via Google OAuth on first use. Rate limits: 40 req/hr, 200 req/day.", + "type": "sse", + "url": "https://influxdb-docs.mcp.kapa.ai" + }, "influxdata": { - "comment": "Use Node to run Docs MCP. To install and setup, see https://github.com/influxdata/docs-mcp-server", + "comment": "Local Docs MCP server (optional). To install and setup, see https://github.com/influxdata/docs-mcp-server. NOTE: uses deprecated endpoints--pending update.", "type": "stdio", "command": "node", "args": [ "${DOCS_MCP_SERVER_PATH}/dist/index.js" ], "env": { - "DOCS_API_KEY_FILE": "${DOCS_API_KEY_FILE:-$HOME/.env.docs-kapa-api-key}", - "DOCS_MODE": "external-only", - "MCP_LOG_LEVEL": "${MCP_LOG_LEVEL:-info}", + "INFLUXDATA_DOCS_API_KEY_FILE": "${INFLUXDATA_DOCS_API_KEY_FILE:-$HOME/.env.docs-kapa-api-key}", + "INFLUXDATA_DOCS_MODE": "external-only", + "INFLUXDATA_DOCS_LOG_LEVEL": "${INFLUXDATA_DOCS_LOG_LEVEL:-info}", "NODE_ENV": "${NODE_ENV:-production}" } } } -} \ No newline at end of file +} diff --git a/AGENTS.md b/AGENTS.md index c05d86e2b..bd27e9efa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,84 @@ | Test code blocks | `yarn test:codeblocks:all` | 15-45m — **NEVER CANCEL** | | Lint | `yarn lint` | ~1m | +## Repository Structure + +``` +docs-v2/ +├── content/ # Documentation content +│ ├── influxdb3/ # InfluxDB 3 (core, enterprise, cloud-*) +│ ├── influxdb/ # InfluxDB v2 and v1 +│ ├── enterprise_influxdb/ # InfluxDB Enterprise v1 +│ ├── telegraf/ # Telegraf docs +│ ├── shared/ # Shared content across products +│ └── example.md # Shortcode testing playground +├── layouts/ # Hugo templates and shortcodes +├── assets/ # JS, CSS, TypeScript +├── api-docs/ # InfluxDB OpenAPI specifications, API reference documentation generation scripts +├── data/ # YAML/JSON data files +├── public/ # Build output (gitignored, ~529MB) +└── .github/ + └── copilot-instructions.md # Primary AI instructions +``` + +**Content Paths**: See [copilot-instructions.md](.github/copilot-instructions.md#content-organization) + +## Documentation MCP Server + +A hosted MCP server provides semantic search over all InfluxDB documentation. +Use it to verify technical accuracy, check API syntax, and find related docs. + +See the [InfluxDB documentation MCP server guide](https://docs.influxdata.com/influxdb3/core/admin/mcp-server/) for setup instructions. + +## Common Workflows + +### Creating/Editing Content + +**Frontmatter** (page metadata): +```yaml +title: Page Title # Required - becomes h1 +description: Brief desc # Required - for SEO +menu: + influxdb_2_0: + name: Nav Label # Optional - nav display name + parent: Parent Node # Optional - for nesting +weight: 1 # Required - sort order +``` + +**Shared Content** (avoid duplication): +```yaml +source: /shared/path/to/content.md +``` + +Shared content files (`/shared/path/to/content.md`): +- Don't store frontmatter +- Can use `{{% show-in %}}`, `{{% hide-in %}}`, and the `version` keyword (`/influxdb3/version/content.md`) + +**Common Shortcodes**: +- Callouts: `> [!Note]`, `> [!Warning]`, `> [!Important]`, `> [!Tip]` +- Tabs: `{{< tabs-wrapper >}}` + `{{% tabs %}}` + `{{% tab-content %}}` +- Required: `{{< req >}}` or `{{< req type="key" >}}` +- Code placeholders: `{ placeholders="" }` + +**📖 Complete Reference**: [DOCS-SHORTCODES.md](DOCS-SHORTCODES.md) | [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md) + +### Testing Changes + +**Always test before committing**: +```bash +# Verify server renders (check 200 status) +curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/ + +# Test specific content +yarn test:links content/influxdb3/core/**/*.md + +# Run style linting +.ci/vale/vale.sh content/**/*.md +``` + +**📖 Complete Reference**: [DOCS-TESTING.md](DOCS-TESTING.md) + + ## Constraints - **NEVER cancel** Hugo builds (~75s) or test runs (15-45m) — the site has 5,359+ pages diff --git a/CLAUDE.md b/CLAUDE.md index a549ac075..dc8350d2b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,16 @@ > - Specialized agents in `.claude/agents/` > - Custom skills in `.claude/skills/` +## Documentation MCP server + +This repo includes [`.mcp.json`](.mcp.json) with a hosted InfluxDB documentation search server. +Use it to verify technical accuracy, check API syntax, and find related docs. + +- **`influxdb-docs`** — API key auth. Set `INFLUXDATA_DOCS_KAPA_API_KEY` env var before launching Claude Code. +- **`influxdb-docs-oauth`** — OAuth fallback. No setup needed. + +See [content-editing skill](.claude/skills/content-editing/SKILL.md#part-4-fact-checking-with-the-documentation-mcp-server) for usage details. + ## Purpose and scope Claude should help document InfluxData products by creating clear, accurate technical content with proper code examples, frontmatter, and formatting.