{
"markdown": "\n\n# π codewiki-mcp\n\n**MCP server for codewiki.google β search, fetch docs, and ask questions about any open-source repo**\n\n[](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/ci.yml)\n[](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/release.yml)\n[](https://www.npmjs.com/package/codewiki-mcp)\n[](https://www.npmjs.com/package/codewiki-mcp)\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://nodejs.org/)\n\n[π·πΊ Π ΡΡΡΠΊΠΈΠΉ](README.ru.md) | **π¬π§ English**\n\n
\n\n*MCP server that connects any AI assistant to [codewiki.google](https://codewiki.google) β AI-generated wiki documentation for open-source repositories.*\n\n
\n\n---\n\n## π Overview\n\n**codewiki-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants access to **codewiki.google** β a service that generates comprehensive wiki documentation for any GitHub repository. Search repos, fetch full docs, or ask natural-language questions β all through MCP.\n\n---\n\n## β¨ Features\n\n| Feature | Description |\n|---------|-------------|\n| π **Search Repos** | Find repositories indexed by codewiki.google |\n| π **Fetch Wiki Docs** | Get full markdown or structured pages for any repo |\n| π¬ **Ask Questions** | Natural-language Q&A with conversation history |\n| π§ **NLP Repo Resolution** | Type naturally β wink-nlp extracts keywords and resolves to `owner/repo` |\n| π‘ **Multiple Transports** | stdio (default), Streamable HTTP, SSE |\n| π **Retry with Backoff** | Automatic retries with exponential backoff on 5xx errors |\n| π³ **Docker Support** | Multi-stage Alpine build |\n| π **Response Metadata** | Byte count and elapsed time on every response |\n\n---\n\n## π Quick Start\n\n### Using npx (no install)\n\n```bash\nnpx -y codewiki-mcp@latest\n```\n\n### From source\n\n```bash\ngit clone https://github.com/izzzzzi/codewiki-mcp.git\ncd codewiki-mcp\nnpm install\nnpm run build\n```\n\n### Transports\n\n```bash\n# stdio (default)\nnode dist/cli.js\n\n# Streamable HTTP\nnode dist/cli.js --http --port 3000\n\n# SSE\nnode dist/cli.js --sse --port 3001\n```\n\n### π³ Docker\n\n```bash\ndocker build -t codewiki-mcp .\n\n# stdio\ndocker run -it --rm codewiki-mcp\n\n# HTTP\ndocker run -p 3000:3000 codewiki-mcp --http\n\n# with environment variables\ndocker run -p 3000:3000 \\\n -e CODEWIKI_REQUEST_TIMEOUT=60000 \\\n -e CODEWIKI_MAX_RETRIES=5 \\\n -e GITHUB_TOKEN=ghp_your_token \\\n codewiki-mcp --http\n```\n\n---\n\n## π§ MCP Client Configuration\n\n\nCursor
\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"codewiki-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codewiki-mcp@latest\"]\n }\n }\n}\n```\n\n \n\n\nClaude Desktop
\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"codewiki-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codewiki-mcp@latest\"]\n }\n }\n}\n```\n\n \n\n\nClaude Code
\n\n```bash\nclaude mcp add codewiki-mcp -- npx -y codewiki-mcp@latest\n```\n\n \n\n\nWindsurf
\n\nAdd to your Windsurf MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"codewiki-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codewiki-mcp@latest\"]\n }\n }\n}\n```\n\n \n\n\nVS Code (Copilot)
\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"codewiki-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codewiki-mcp@latest\"]\n }\n }\n}\n```\n\n \n\n\nLocal development
\n\n```json\n{\n \"mcpServers\": {\n \"codewiki-mcp\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/codewiki-mcp/dist/cli.js\"]\n }\n }\n}\n```\n\n \n\n---\n\n## π‘ Usage\n\nPrompts you can use in any MCP-compatible client:\n\n```\ncodewiki fetch how routing works in Next.js\n```\n\n```\ncodewiki search state management libraries\n```\n\n```\ncodewiki ask how does React fiber reconciler work?\n```\n\nFetch complete documentation:\n\n```\ncodewiki fetch vercel/next.js\ncodewiki fetch https://github.com/fastify/fastify\n```\n\nGet structured pages:\n\n```\ncodewiki fetch pages tailwindlabs/tailwindcss\n```\n\nAsk with natural language:\n\n```\ncodewiki ask fastify how to add authentication?\n```\n\n---\n\n## π οΈ MCP Tools\n\n### π codewiki_search_repos\n\nSearch repositories indexed by codewiki.google.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|:--------:|---------|-------------|\n| `query` | string | β
| β | Search query |\n| `limit` | number | β | 10 | Max results (1β50) |\n\n### π codewiki_fetch_repo\n\nFetch generated wiki content for a repository.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|:--------:|---------|-------------|\n| `repo` | string | β
| β | `owner/repo`, GitHub URL, or natural-language query |\n| `mode` | string | β | `\"aggregate\"` | `\"aggregate\"` β full markdown; `\"pages\"` β structured JSON |\n\n### π¬ codewiki_ask_repo\n\nAsk a natural-language question about a repository.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|:--------:|---------|-------------|\n| `repo` | string | β
| β | Repository identifier (same formats as fetch) |\n| `question` | string | β
| β | Question about the repo |\n| `history` | array | β | `[]` | Conversation history `[{role, content}]` (max 20) |\n\n---\n\n## π Response Format\n\n\nβ
Success β Search
\n\n```json\n{\n \"query\": \"fastify\",\n \"count\": 1,\n \"items\": [\n {\n \"fullName\": \"fastify/fastify\",\n \"url\": \"https://github.com/fastify/fastify\",\n \"description\": \"Fast and low overhead web framework\",\n \"avatarUrl\": \"https://avatars.githubusercontent.com/u/24939....\",\n \"extraScore\": 555\n }\n ],\n \"meta\": {\n \"totalBytes\": 12500,\n \"totalElapsedMs\": 450\n }\n}\n```\n\n \n\n\nβ
Success β Fetch (pages mode)
\n\n```json\n{\n \"repo\": \"fastify/fastify\",\n \"commit\": \"abc123\",\n \"canonicalUrl\": \"https://github.com/fastify/fastify\",\n \"pages\": [\n {\n \"title\": \"Overview\",\n \"level\": 1,\n \"anchor\": \"#overview\",\n \"markdown\": \"# Overview\\n\\nFastify is a web framework...\",\n \"diagramCount\": 1\n }\n ],\n \"meta\": {\n \"totalBytes\": 25000,\n \"totalElapsedMs\": 1200\n }\n}\n```\n\n \n\n\nβ
Success β Ask
\n\n```json\n{\n \"answer\": \"Fastify uses a plugin-based architecture where...\",\n \"meta\": {\n \"totalBytes\": 8500,\n \"totalElapsedMs\": 2300\n }\n}\n```\n\n \n\n\nβ Error Response
\n\n```json\n{\n \"error\": {\n \"code\": \"RPC_FAIL\",\n \"message\": \"CodeWiki RPC VSX6ub failed with status 404\",\n \"rpcId\": \"VSX6ub\",\n \"statusCode\": 404\n }\n}\n```\n\nError codes: `VALIDATION`, `RPC_FAIL`, `TIMEOUT`, `NLP_RESOLVE_FAIL`\n\n \n\n---\n\n## βοΈ How It Works\n\n### Data Flow\n\n```\nAI Assistant β MCP protocol β codewiki-mcp β HTTPS β codewiki.google\n β\nAI Assistant β MCP protocol β codewiki-mcp β JSON β Google RPC API\n```\n\n### Google Batchexecute RPC\n\ncodewiki.google uses Google's internal **batchexecute** RPC format (not REST, not GraphQL). The client:\n\n1. Builds a POST request with `f.req=...` body\n2. Sends it to `/_/BoqAngularSdlcAgentsUi/data/batchexecute`\n3. Receives a response with XSSI prefix `)]}'\\n`\n4. Parses `wrb.fr` frames and extracts the typed payload\n\nEach tool maps to an RPC ID:\n\n| Tool | RPC ID |\n|------|:------:|\n| π Search | `vyWDAf` |\n| π Fetch | `VSX6ub` |\n| π¬ Ask | `EgIxfe` |\n\n### π§ NLP Repo Resolution\n\nUsers can type natural language instead of `owner/repo`:\n\n```\n\"the fastify web framework\"\n β wink-nlp extracts keyword \"fastify\" (POS tag: NOUN/PROPN)\n β GitHub Search API: GET /search/repositories?q=fastify&sort=stars\n β top result: \"fastify/fastify\"\n β normalizeRepoInput(\"fastify/fastify\") β URL for codewiki\n```\n\n### π Retry with Exponential Backoff\n\n| Attempt | Delay |\n|:-------:|------:|\n| 0 | immediate |\n| 1 | 250ms |\n| 2 | 500ms |\n| 3 | 1000ms |\n\n> 4xx errors (client errors) are never retried.\n\n---\n\n## π₯οΈ CLI\n\n```\ncodewiki-mcp [options]\n\nOptions:\n --http Streamable HTTP transport\n --sse SSE transport\n --port Port for HTTP/SSE (default: 3000)\n --endpoint URL endpoint (default: /mcp)\n --help, -h Show help\n```\n\n---\n\n## β‘ Configuration\n\nEnvironment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CODEWIKI_BASE_URL` | `https://codewiki.google` | Base URL |\n| `CODEWIKI_REQUEST_TIMEOUT` | `30000` | Request timeout (ms) |\n| `CODEWIKI_MAX_RETRIES` | `3` | Max retries |\n| `CODEWIKI_RETRY_DELAY` | `250` | Base retry delay (ms) |\n| `GITHUB_TOKEN` | β | GitHub token for NLP repo resolution |\n\nYou can also create a `.env` file in the project root:\n\n```\nCODEWIKI_REQUEST_TIMEOUT=60000\nCODEWIKI_MAX_RETRIES=5\nGITHUB_TOKEN=ghp_your_token\n```\n\n---\n\n## π Project Structure\n\n```\nsrc/\nβββ cli.ts # CLI entry point\nβββ server.ts # Transport setup (stdio/HTTP/SSE)\nβββ index.ts # Library re-exports\nβββ schemas.ts # Zod input schemas\nβββ lib/\nβ βββ codewikiClient.ts # API client with retry + metadata\nβ βββ batchexecute.ts # Google RPC response parser\nβ βββ repo.ts # Repo normalization + NLP resolution\nβ βββ extractKeyword.ts # NLP keyword extraction (wink-nlp)\nβ βββ resolveRepo.ts # GitHub Search API resolver\nβ βββ errors.ts # CodeWikiError + formatMcpError\nβ βββ config.ts # Env-based configuration\nβββ tools/\n βββ searchRepos.ts # codewiki_search_repos\n βββ fetchRepo.ts # codewiki_fetch_repo\n βββ askRepo.ts # codewiki_ask_repo\n```\n\n---\n\n## β Troubleshooting\n\n\nPermission Denied
\n\n```bash\nchmod +x ./node_modules/.bin/codewiki-mcp\n```\n\n \n\n\nConnection Refused (HTTP/SSE)
\n\n```bash\n# Check if port is in use\nlsof -i :3000\n```\n\n \n\n\nTimeout Errors
\n\nFor large repositories, increase the timeout:\n\n```bash\nCODEWIKI_REQUEST_TIMEOUT=60000 node dist/cli.js\n```\n\n \n\n\nNLP Resolution Fails
\n\nIf natural-language input doesn't resolve, use explicit format:\n\n```\n# Instead of \"the fastify framework\"\nfastify/fastify\n# or\nhttps://github.com/fastify/fastify\n```\n\nSet `GITHUB_TOKEN` to avoid GitHub API rate limits for unauthenticated requests.\n\n \n\n---\n\n## π§βπ» Development\n\n```bash\nnpm run dev # stdio with tsx\nnpm run dev:http # HTTP with tsx\nnpm run dev:sse # SSE with tsx\nnpm run typecheck # type check\nnpm run test # run tests\nnpm run test:watch # tests in watch mode\nnpm run build # compile to dist/\n```\n\n---\n\n## π€ Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feat/my-feature`)\n3. Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages\n4. Run `npm run typecheck && npm run test` before submitting\n5. Open a Pull Request\n\n---\n\n## π License\n\n[MIT](LICENSE) Β© codewiki-mcp contributors\n",
"bytes": 11870,
"sha": "8be8d45d2e4df0266465346488241e910795b6d00c02c576bc6b47872efa12bb",
"repo_slug": "izzzzzi/codewiki-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_izzzzzi_codewiki_mcp_22b9b9e9/readme"
}