From d58ccf7c58d60e5e0d3db49baaaf4f39e8e1607a Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Thu, 22 Oct 2026 11:51:55 +0300 Subject: [PATCH 1/2] fix(docs): curate LLM exports and correct authentication guidance --- docs/api/mcp-protocol.md | 18 ++++++- docs/intro.md | 2 +- website/docusaurus.config.js | 45 ++++-------------- website/package.json | 4 +- website/published-docs.js | 29 ++++++++++++ website/scripts/verify-docs-build.js | 49 ++++++++++++++++++++ website/sidebars.js | 14 +++--- website/static/img/mcpproxy-architecture.svg | 9 ++++ website/static/robots.txt | 4 ++ 9 files changed, 127 insertions(+), 47 deletions(-) create mode 100644 website/published-docs.js create mode 100644 website/scripts/verify-docs-build.js create mode 100644 website/static/img/mcpproxy-architecture.svg create mode 100644 website/static/robots.txt diff --git a/docs/api/mcp-protocol.md b/docs/api/mcp-protocol.md index 4b00f9ef8..47f9a1cad 100644 --- a/docs/api/mcp-protocol.md +++ b/docs/api/mcp-protocol.md @@ -34,7 +34,23 @@ Each routing mode has a dedicated endpoint that is always available regardless o See [Routing Modes](../features/routing-modes.md) for details on each mode. -**Note:** MCP endpoints do not require API key authentication for client compatibility. +### Authentication + +Authentication depends on the deployment and transport: + +| Surface | Authentication | +| --- | --- | +| Local MCP over HTTP, default configuration | Authentication is optional (`require_mcp_auth: false`). Anonymous callers retain admin-level tool and management access for compatibility, subject to enabled tools and configuration gates; they cannot use the opt-in raw secret-header reveal. | +| MCP over HTTP with `require_mcp_auth: true` | Requires a valid credential, such as an admin API key or a scoped agent token. Enable this before exposing MCP beyond localhost. | +| Server edition with `server_edition.enabled: true` | Forces MCP authentication on, even if `require_mcp_auth` is explicitly false. | +| REST API over HTTP | Requires authentication independently of `require_mcp_auth`. | +| Local Unix socket / Windows named pipe | Uses OS-level access control; trusted local connections do not need an API key. | + +See [configuration defaults](/configuration/config-file#server-settings), +[agent tokens and MCP authentication](/features/agent-tokens#enforcing-authentication-on-mcp), +[REST authentication](/api/rest-api#authentication), and +[Server edition authentication](/development/server-edition-multiuser-auth) +for credential formats and access rules. ## Built-in Tools diff --git a/docs/intro.md b/docs/intro.md index b4d36af99..85e14b0d6 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -12,7 +12,7 @@ keywords: [mcp, proxy, ai agents, tool discovery, security, docker] **A smart proxy for AI agents using the Model Context Protocol (MCP)** -![MCPProxy Architecture](/img/mcpproxy-architecture.jpeg) +![AI clients connect to MCPProxy, which discovers tools across upstream MCP servers. Review and isolation controls reduce risk but do not guarantee safety.](/img/mcpproxy-architecture.svg) ## What is MCPProxy? diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 8fd119956..494e59016 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -2,6 +2,7 @@ // Note: type annotations allow type checking and IDEs autocompletion const {themes: prismThemes} = require('prism-react-renderer'); +const publishedDocs = require('./published-docs'); /** @type {import('@docusaurus/types').Config} */ // Version shown in the navbar badge. Supplied by CI: docs.yml derives it from @@ -53,35 +54,11 @@ const config = { routeBasePath: '/', // docs at root sidebarPath: './sidebars.js', editUrl: 'https://github.com/smart-mcp-proxy/mcpproxy-go/edit/main/', - // Only include structured documentation pages - include: [ - 'intro.md', - 'getting-started/**/*.{md,mdx}', - 'configuration/**/*.{md,mdx}', - 'cli/**/*.{md,mdx}', - 'api/**/*.{md,mdx}', - 'web-ui/**/*.{md,mdx}', - 'features/**/*.{md,mdx}', - 'code_execution/**/*.{md,mdx}', - 'operations/**/*.{md,mdx}', - 'errors/**/*.{md,mdx}', - 'development/**/*.{md,mdx}', - 'contributing.md', - // Standalone references with no structured counterpart - 'cli-client-mode.md', - 'cli-output-formatting.md', - 'logging.md', - 'prerelease-builds.md', - 'registries.md', - 'socket-communication.md', - ], - // Internal working documents that live in the repo but are not published - exclude: [ - 'development/sandbox-snap-docker-harness.md', - 'development/sandbox-spike-mcp-34.md', - ], + include: publishedDocs.include, + exclude: publishedDocs.exclude, }, blog: false, + sitemap: { ignorePatterns: ['/search'] }, theme: { customCss: './src/css/custom.css', }, @@ -97,16 +74,10 @@ const config = { generateLLMsFullTxt: true, excludeImports: true, removeDuplicateHeadings: true, - includeOrder: [ - 'getting-started/*', - 'configuration/*', - 'cli/*', - 'api/*', - 'web-ui/*', - 'features/*', - 'code_execution/*', - 'operations/*', - ], + docsDir: [{ path: 'docs', routeBasePath: '/' }], + includeOrder: publishedDocs.include, + includeUnmatchedLast: false, + ignoreFiles: publishedDocs.exclude, }, ], ], diff --git a/website/package.json b/website/package.json index 3897d1176..0f3d5fef7 100644 --- a/website/package.json +++ b/website/package.json @@ -11,7 +11,9 @@ "clear": "docusaurus clear", "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", - "write-heading-ids": "docusaurus write-heading-ids" + "write-heading-ids": "docusaurus write-heading-ids", + "postbuild": "node scripts/verify-docs-build.js", + "verify:build": "node scripts/verify-docs-build.js" }, "dependencies": { "@docusaurus/core": "^3.10.2", diff --git a/website/published-docs.js b/website/published-docs.js new file mode 100644 index 000000000..fa32dba8d --- /dev/null +++ b/website/published-docs.js @@ -0,0 +1,29 @@ +// Shared publication boundary for HTML pages and both LLM exports. +// Keep internal research, plans and QA notes outside these patterns. +module.exports = { + include: [ + 'intro.md', + 'getting-started/**/*.{md,mdx}', + 'configuration/**/*.{md,mdx}', + 'cli/**/*.{md,mdx}', + 'api/**/*.{md,mdx}', + 'web-ui/**/*.{md,mdx}', + 'features/**/*.{md,mdx}', + 'code_execution/**/*.{md,mdx}', + 'operations/**/*.{md,mdx}', + 'errors/**/*.{md,mdx}', + 'development/**/*.{md,mdx}', + 'contributing.md', + // Standalone references with no structured counterpart + 'cli-client-mode.md', + 'cli-output-formatting.md', + 'logging.md', + 'prerelease-builds.md', + 'registries.md', + 'socket-communication.md', + ], + exclude: [ + 'development/sandbox-snap-docker-harness.md', + 'development/sandbox-spike-mcp-34.md', + ], +}; diff --git a/website/scripts/verify-docs-build.js b/website/scripts/verify-docs-build.js new file mode 100644 index 000000000..5256f4a5e --- /dev/null +++ b/website/scripts/verify-docs-build.js @@ -0,0 +1,49 @@ +#!/usr/bin/env node +// Verify the actual generated artifacts, not just the source glob settings. +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const siteDir = path.resolve(__dirname, '..'); +const buildDir = path.join(siteDir, 'build'); +const metadataDir = path.join(siteDir, '.docusaurus/docusaurus-plugin-content-docs/default'); +const normalize = value => new URL(value, 'https://docs.mcpproxy.app').pathname.replace(/\/$/, '') || '/'; +const read = file => fs.readFileSync(path.join(buildDir, file), 'utf8'); +const metadata = fs.readdirSync(metadataDir) + .filter(file => file.endsWith('.json') && !file.startsWith('__')) + .map(file => JSON.parse(fs.readFileSync(path.join(metadataDir, file), 'utf8'))) + .filter(doc => doc.source && doc.permalink && !doc.draft && !doc.unlisted); +assert(metadata.length > 0, 'No published document metadata found'); +const published = new Set(metadata.map(doc => normalize(doc.permalink))); +const index = read('llms.txt'); +const links = [...index.matchAll(/^- \[[^\n]*\]\((https:\/\/docs\.mcpproxy\.app[^)\s]*)\)/gm)].map(match => match[1]); +assert(links.length > 0, 'LLM index is empty'); +const exported = new Set(); +for (const link of links) { + const route = normalize(link); + assert(published.has(route), `LLM export links to unpublished page: ${link}`); + assert(!exported.has(route), `Duplicate LLM export route: ${link}`); + exported.add(route); + const relative = route.replace(/^\//, ''); + assert([path.join(buildDir, relative, 'index.html'), path.join(buildDir, `${relative}.html`)] + .some(file => fs.existsSync(file)), `LLM export has no built HTML page: ${link}`); +} +assert.deepEqual([...exported].sort(), [...published].sort(), 'LLM index must cover every published document'); +const full = read('llms-full.txt'); +assert(full.length > index.length, 'Full LLM export is empty or incomplete'); +// Regressions from the original export: excluded docs had no HTML routes but +// their bodies (including agent workflow instructions) appeared in llms-full. +for (const marker of [ + 'CRITICAL SECURITY VULNERABILITY: Skipped API Key Tests', + 'REQUIRED SUB-SKILL:', + 'TPA Scanner: Inline Findings & Background Scanning — Authoritative Design', +]) { + assert(!full.includes(marker), `Unpublished content in full LLM export: ${marker}`); +} +assert(!/https:\/\/docs\.mcpproxy\.app\/search\/?<\/loc>/.test(read('sitemap.xml')), 'Noindexed search page is in sitemap'); +assert(read('robots.txt').includes('Sitemap: https://docs.mcpproxy.app/sitemap.xml'), 'robots.txt is missing sitemap declaration'); +for (const category of ['getting-started', 'configuration', 'cli', 'api', 'web-ui', 'features', 'operations']) { + const html = fs.existsSync(path.join(buildDir, category, 'index.html')) ? read(`${category}/index.html`) : read(`${category}.html`); + assert(/]*name="description"[^>]*content="[^"]+"/.test(html), `Missing category description: ${category}`); +} +console.log(`Verified ${exported.size} published LLM links, full-export regression markers, category metadata, sitemap and robots.txt.`); diff --git a/website/sidebars.js b/website/sidebars.js index 7b3071c6e..2ee04f2e7 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -24,7 +24,7 @@ const sidebars = { // reads _category_.json for AUTOGENERATED sidebars. Without this the // /getting-started URL 404s, which is where the marketing site's // "Getting Started" card used to land. - link: { type: 'generated-index', slug: '/getting-started' }, + link: { type: 'generated-index', slug: '/getting-started', description: 'Install MCPProxy and make your first successful MCP tool call.' }, items: [ 'getting-started/installation', 'getting-started/quick-start', @@ -34,7 +34,7 @@ const sidebars = { type: 'category', label: 'Configuration', // See the note on Getting Started above — same reason. - link: { type: 'generated-index', slug: '/configuration' }, + link: { type: 'generated-index', slug: '/configuration', description: 'Configure MCPProxy, upstream servers, environment variables and sensitive data detection.' }, items: [ 'configuration/config-file', 'configuration/upstream-servers', @@ -45,7 +45,7 @@ const sidebars = { { type: 'category', label: 'CLI', - link: { type: 'generated-index', slug: '/cli' }, + link: { type: 'generated-index', slug: '/cli', description: 'Manage MCPProxy servers, profiles, security reviews and activity from the command line.' }, items: [ 'cli/command-reference', 'cli/management-commands', @@ -66,7 +66,7 @@ const sidebars = { { type: 'category', label: 'API', - link: { type: 'generated-index', slug: '/api' }, + link: { type: 'generated-index', slug: '/api', description: 'Integrate with the MCPProxy REST API and MCP protocol endpoints.' }, items: [ 'api/rest-api', 'api/mcp-protocol', @@ -75,7 +75,7 @@ const sidebars = { { type: 'category', label: 'Web UI', - link: { type: 'generated-index', slug: '/web-ui' }, + link: { type: 'generated-index', slug: '/web-ui', description: 'Use the MCPProxy dashboard to manage servers, settings and activity.' }, items: [ 'web-ui/dashboard', 'web-ui/server-detail', @@ -86,7 +86,7 @@ const sidebars = { { type: 'category', label: 'Features', - link: { type: 'generated-index', slug: '/features' }, + link: { type: 'generated-index', slug: '/features', description: 'Explore tool discovery, routing, client connections and security controls.' }, items: [ 'features/routing-modes', 'features/schema-deferred-direct-mode', @@ -156,7 +156,7 @@ const sidebars = { { type: 'category', label: 'Operations', - link: { type: 'generated-index', slug: '/operations' }, + link: { type: 'generated-index', slug: '/operations', description: 'Deploy, monitor and maintain MCPProxy locally or for a team.' }, items: [ 'operations/reverse-proxy', 'operations/deploying-for-a-team', diff --git a/website/static/img/mcpproxy-architecture.svg b/website/static/img/mcpproxy-architecture.svg new file mode 100644 index 000000000..10e8afcfe --- /dev/null +++ b/website/static/img/mcpproxy-architecture.svg @@ -0,0 +1,9 @@ + +MCPProxy architecture +AI clients connect to MCPProxy, which discovers tools across upstream MCP servers. Review and isolation controls reduce risk but do not guarantee safety. + + + + +AI clientsMCPProxyMCP serversOne proxy connectionDiscover and call toolsReview new serversInspect activity recordsLocal or remote toolsReview and isolation reduce risk; they do not guarantee safety. + diff --git a/website/static/robots.txt b/website/static/robots.txt new file mode 100644 index 000000000..1cb2eede3 --- /dev/null +++ b/website/static/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://docs.mcpproxy.app/sitemap.xml From a70eb17d2434cd4a55353cb7245bfa2bcced15a1 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Thu, 22 Oct 2026 12:36:56 +0300 Subject: [PATCH 2/2] fix(docs): preserve release-gate publication list parsing --- website/docusaurus.config.js | 33 ++++++++++++++++++++++++++++++++- website/published-docs.js | 29 ----------------------------- 2 files changed, 32 insertions(+), 30 deletions(-) delete mode 100644 website/published-docs.js diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 494e59016..c5ed08f8a 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -2,7 +2,38 @@ // Note: type annotations allow type checking and IDEs autocompletion const {themes: prismThemes} = require('prism-react-renderer'); -const publishedDocs = require('./published-docs'); + +// Shared publication boundary for HTML pages and both LLM exports. +// Keep internal research, plans and QA notes outside these patterns. +// Keep these literal lists here: cmd/release-gate also reads them to guard +// claims and links across every published page. +const publishedDocs = { + include: [ + 'intro.md', + 'getting-started/**/*.{md,mdx}', + 'configuration/**/*.{md,mdx}', + 'cli/**/*.{md,mdx}', + 'api/**/*.{md,mdx}', + 'web-ui/**/*.{md,mdx}', + 'features/**/*.{md,mdx}', + 'code_execution/**/*.{md,mdx}', + 'operations/**/*.{md,mdx}', + 'errors/**/*.{md,mdx}', + 'development/**/*.{md,mdx}', + 'contributing.md', + // Standalone references with no structured counterpart + 'cli-client-mode.md', + 'cli-output-formatting.md', + 'logging.md', + 'prerelease-builds.md', + 'registries.md', + 'socket-communication.md', + ], + exclude: [ + 'development/sandbox-snap-docker-harness.md', + 'development/sandbox-spike-mcp-34.md', + ], +}; /** @type {import('@docusaurus/types').Config} */ // Version shown in the navbar badge. Supplied by CI: docs.yml derives it from diff --git a/website/published-docs.js b/website/published-docs.js deleted file mode 100644 index fa32dba8d..000000000 --- a/website/published-docs.js +++ /dev/null @@ -1,29 +0,0 @@ -// Shared publication boundary for HTML pages and both LLM exports. -// Keep internal research, plans and QA notes outside these patterns. -module.exports = { - include: [ - 'intro.md', - 'getting-started/**/*.{md,mdx}', - 'configuration/**/*.{md,mdx}', - 'cli/**/*.{md,mdx}', - 'api/**/*.{md,mdx}', - 'web-ui/**/*.{md,mdx}', - 'features/**/*.{md,mdx}', - 'code_execution/**/*.{md,mdx}', - 'operations/**/*.{md,mdx}', - 'errors/**/*.{md,mdx}', - 'development/**/*.{md,mdx}', - 'contributing.md', - // Standalone references with no structured counterpart - 'cli-client-mode.md', - 'cli-output-formatting.md', - 'logging.md', - 'prerelease-builds.md', - 'registries.md', - 'socket-communication.md', - ], - exclude: [ - 'development/sandbox-snap-docker-harness.md', - 'development/sandbox-spike-mcp-34.md', - ], -};