Doc Tools MCP Server (#157)

* Init MCP

* Add comprehensive documentation for extensions and macros

- Add development guides for extensions and macros
- Add user guides with examples and usage patterns
- Add reference documentation for APIs
- Add README files for both components

* Add MCP server implementation and tests

- Implement MCP server with tool handlers
- Add comprehensive test suite for MCP functionality
- Add MCP tools directory with server utilities

* Update CLI tools for MCP integration

- Enhance doc-tools-mcp.js with improved tool handlers
- Update doc-tools.js with new command routing
- Refactor setup-mcp.js for better initialization

* Add GitHub Actions workflow for MCP testing

* Add CLI documentation generation tooling

- Add script to generate CLI reference documentation
- Add generated CLI reference in AsciiDoc format

* Add contributing guidelines

* Update package.json with new dependencies

* Update README with improved documentation structure

- Simplify main README
- Reference new documentation files for details

* Remove deprecated MCP_SERVER.md

Documentation moved to mcp/README.adoc

* Bump version

* Allow MCP server to work from any repo with doc-tools installed

Previously, the MCP server only worked when run from the
docs-extensions-and-macros source repository by checking for
bin/doc-tools.js. This prevented using the MCP server from
documentation repositories that have doc-tools installed as a dependency.

Now the validation:
1. First checks if we're in the source repo (bin/doc-tools.js exists)
2. Falls back to checking if doc-tools is available via npx

This allows the MCP server to work from any repository that has
doc-tools installed or available, while still working from the
source repository for development.

* Apply suggestions

* Fix tests

* Apply suggestions

* Apply suggestions

* Apply suggestions

* Improve schema

* Add background job support to rpk and metrics

* Fix defaults issue

* Allow for local dev

* Retry logic

* Add unified support for tokens

* Fix docker commands

* Remove cloud restriction

* Fix name

* Rearchitect MCP server for writer extensibility

* Update crd-docs to support local mode

* Improve reviews

* Fix tests

Author: JakeSCahill

.github/workflows/test-mcp.yml

@@ -0,0 +1,77 @@
+name: Test MCP Server
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'bin/**'
+      - '__tests__/mcp/**'
+      - 'package.json'
+  pull_request:
+    paths:
+      - 'bin/**'
+      - '__tests__/mcp/**'
+      - 'package.json'
+
+permissions:
+  checks: write
+  pull-requests: write
+  contents: read
+
+jobs:
+  test-mcp:
+    name: Test MCP Server Integration
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run MCP integration tests
+        run: npm test -- __tests__/mcp/
+        env:
+          # Set test timeout for network operations
+          JEST_TIMEOUT: 30000
+
+      - name: Report test results
+        if: always()
+        uses: dorny/test-reporter@v1
+        with:
+          name: MCP Test Results
+          path: 'test-results/**/*.xml'
+          reporter: jest-junit
+          fail-on-error: true
+
+  test-cli-contract:
+    name: Verify CLI Contract
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run CLI contract tests
+        run: npm test -- __tests__/mcp/cli-contract.test.js
+
+      - name: Verify all generate commands exist
+        run: |
+          echo "Verifying generate commands..."
+          npx doc-tools generate --help | grep -E "(property-docs|metrics-docs|rpk-docs|rpcn-connector-docs|helm-spec|cloud-regions|crd-spec|bundle-openapi)"

.gitignore

@@ -8,6 +8,9 @@ __pycache__/
 gen/
 tree-sitter/
 test/
+test-results/
 modules/
 cloud-controlplane/
 node_modules
+.env
+mcp-usage-stats.json