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