feat: add MCP server Docker support and AI agent integration docs

Add Docker integration for the MCP server so it runs alongside FastAPI
and Next.js inside the container on port 8008 (streamable-http transport).

Changes:
- Dockerfile: expose port 8008, launch MCP server in start.sh
- docker-compose.yml: add 8008:8008 port mapping
- api/mcp/server.py: bind to 0.0.0.0 in HTTP mode (configurable via
  MCP_HOST/MCP_PORT env vars) for Docker container accessibility
- api/pyproject.toml: add mcp[cli] as Poetry dependency
- api/poetry.lock: regenerated with mcp[cli] and transitive deps
- MCP_SETUP.md: replace "Optional, Future" Docker section with working
  setup docs including Claude Code and Claude Desktop config examples
- README.md: add MCP server section with tool descriptions, Docker and
  local connection instructions, and port reference table

AI agents (Claude Desktop, Claude Code, Cursor, Windsurf) can now query
wiki documentation via 5 MCP tools: list_projects, get_wiki_overview,
get_wiki_page, search_wiki, and ask_codebase.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

Dockerfile

@@ -77,7 +77,7 @@ COPY --from=node_builder /app/.next/standalone ./
 COPY --from=node_builder /app/.next/static ./.next/static
 
 # Expose the port the app runs on
-EXPOSE ${PORT:-8001} 3000
+EXPOSE ${PORT:-8001} 3000 8008
 
 # Create a script to run both backend and frontend
 RUN echo '#!/bin/bash\n\
@@ -95,6 +95,8 @@ fi\n\
 \n\
 # Start the API server in the background with the configured port\n\
 python -m api.main --port ${PORT:-8001} &\n\
+# Start the MCP server on port 8008 (streamable-http transport)\n\
+python /app/api/mcp/server.py --http &\n\
 PORT=3000 HOSTNAME=0.0.0.0 node server.js &\n\
 wait -n\n\
 exit $?' > /app/start.sh && chmod +x /app/start.sh

MCP_SETUP.md

@@ -558,25 +558,35 @@ Expected: Claude calls `ask_codebase`, gets relevant wiki context, then reasons
 
 ---
 
-## Docker Integration (Optional, Future)
+## Docker Integration
 
-If you want the MCP server to run inside the Docker container alongside the existing services, add to `start.sh`:
+The MCP server runs automatically inside the Docker container alongside FastAPI and Next.js.
 
-```bash
-# Start MCP server on port 8008 (HTTP mode for remote access)
-python api/mcp/server.py --http &
-```
+**What's configured:**
+- `mcp[cli]` is included in `api/pyproject.toml` as a Poetry dependency
+- `Dockerfile` exposes port 8008 and launches `python /app/api/mcp/server.py --http &` in `start.sh`
+- `docker-compose.yml` maps port 8008 to the host
+- The server binds to `0.0.0.0:8008` inside the container (configurable via `MCP_HOST` and `MCP_PORT` env vars)
+
+**Usage after `docker compose up`:**
 
-And expose port 8008 in `docker-compose.yml`:
+Remote MCP clients connect to `http://localhost:8008/mcp` (streamable-http transport).
 
-```yaml
-ports:
-  - "8008:8008"   # MCP server
-  - "8001:8001"   # FastAPI
-  - "3000:3000"   # Next.js
+For Claude Code connecting to a Docker-hosted instance:
+```bash
+claude mcp add bettercodewiki --transport streamable-http http://localhost:8008/mcp
 ```
 
-Remote clients would then connect to `http://localhost:8008/mcp`.
+For Claude Desktop, use the URL-based config:
+```json
+{
+  "mcpServers": {
+    "bettercodewiki": {
+      "url": "http://localhost:8008/mcp"
+    }
+  }
+}
+```
 
 ---
 

README.md

@@ -26,6 +26,7 @@
 - **Export Options**: Export to Markdown, JSON, Notion, Confluence, and HTML formats
 - **Global Search**: Command palette (Cmd+K) for quick navigation
 - **Reading Mode**: Distraction-free reading with Alt+R toggle
+- **MCP Server**: Expose wiki data to AI agents (Claude Desktop, Claude Code, Cursor, Windsurf) via Model Context Protocol
 
 ## Quick Start
 
@@ -162,6 +163,8 @@ BetterCodeWiki/
 │   ├── api.py            # FastAPI implementation
 │   ├── rag.py            # Retrieval Augmented Generation
 │   ├── data_pipeline.py  # Data processing utilities
+│   ├── mcp/              # MCP server (standalone)
+│   │   └── server.py     # 5 tools for AI agent access to wikis
 │   ├── pyproject.toml    # Python dependencies (Poetry)
 │   └── poetry.lock       # Locked Python dependency versions
 │
@@ -208,7 +211,7 @@ BetterCodeWiki/
 # Pull and run
 docker pull ghcr.io/asyncfuncai/deepwiki-open:latest
 
-docker run -p 8001:8001 -p 3000:3000 \
+docker run -p 8001:8001 -p 3000:3000 -p 8008:8008 \
   -e GOOGLE_API_KEY=your_key \
   -e OPENAI_API_KEY=your_key \
   -v ~/.adalflow:/root/.adalflow \
@@ -221,6 +224,81 @@ Or use Docker Compose:
 docker-compose up
 ```
 
+### Ports
+
+| Port | Service |
+|------|---------|
+| 3000 | Next.js frontend |
+| 8001 | FastAPI backend |
+| 8008 | MCP server (streamable-http) |
+
+## MCP Server — AI Agent Integration
+
+BetterCodeWiki includes a built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI coding agents query your wiki documentation in real-time.
+
+### What It Does
+
+Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf) can:
+- Discover which repos have generated wikis
+- Look up architecture overviews and specific wiki pages
+- Search documentation for relevant context
+- Ask questions about a codebase using wiki content
+
+### 5 MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | Discover all cached wiki repos |
+| `get_wiki_overview` | Get project architecture in one call |
+| `get_wiki_page` | Fetch a specific page by title (fuzzy match) or ID |
+| `search_wiki` | Full-text search across all wiki pages |
+| `ask_codebase` | Get relevant wiki context for a question |
+
+### Connect via Docker (HTTP)
+
+When running with Docker, the MCP server is available at `http://localhost:8008/mcp`.
+
+**Claude Code:**
+```bash
+claude mcp add bettercodewiki --transport streamable-http http://localhost:8008/mcp
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "bettercodewiki": {
+      "url": "http://localhost:8008/mcp"
+    }
+  }
+}
+```
+
+### Connect Locally (stdio — no Docker needed)
+
+```bash
+# Set up the venv once
+python3 -m venv api/mcp/.venv
+api/mcp/.venv/bin/pip install "mcp[cli]"
+
+# Register with Claude Code
+claude mcp add bettercodewiki -- api/mcp/.venv/bin/python api/mcp/server.py
+```
+
+**Claude Desktop** (stdio mode):
+```json
+{
+  "mcpServers": {
+    "bettercodewiki": {
+      "command": "/absolute/path/to/BetterCodeWiki/api/mcp/.venv/bin/python",
+      "args": ["/absolute/path/to/BetterCodeWiki/api/mcp/server.py"]
+    }
+  }
+}
+```
+
+For full setup details, see [MCP_SETUP.md](MCP_SETUP.md).
+
 ## Ask & DeepResearch
 
 - **Ask**: Chat with your repository using RAG for context-aware, streaming responses

api/mcp/server.py

@@ -411,7 +411,9 @@ def wiki_page_resource(owner: str, repo: str, page_id: str) -> str:
 
 if __name__ == "__main__":
     if "--http" in sys.argv:
-        print("Starting BetterCodeWiki MCP server on http://127.0.0.1:8008/mcp", file=sys.stderr)
-        mcp.run(transport="streamable-http", host="127.0.0.1", port=8008)
+        host = os.environ.get("MCP_HOST", "0.0.0.0")
+        port = int(os.environ.get("MCP_PORT", "8008"))
+        print(f"Starting BetterCodeWiki MCP server on http://{host}:{port}/mcp", file=sys.stderr)
+        mcp.run(transport="streamable-http", host=host, port=port)
     else:
         mcp.run(transport="stdio")