codewiki-mcp 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 codewiki-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,53 +1,49 @@
-# codewiki-mcp
+<div align="center">
 
-MCP server for [codewiki.google](https://codewiki.google) — search, fetch wiki docs, and ask questions about any open-source repository.
+# 📚 codewiki-mcp
 
-[Русская версия](README.ru.md)
+**MCP server for codewiki.google — search, fetch docs, and ask questions about any open-source repo**
 
-## Features
+[![CI](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/ci.yml)
+[![Release](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/izzzzzi/codewiki-mcp/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/codewiki-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D)](https://www.npmjs.com/package/codewiki-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/codewiki-mcp.svg?style=flat&colorA=18181B&colorB=28CF8D)](https://www.npmjs.com/package/codewiki-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat&colorA=18181B&colorB=28CF8D)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat&colorA=18181B&colorB=3178C6)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-ESM-green?style=flat&colorA=18181B&colorB=339933)](https://nodejs.org/)
 
-- **3 MCP tools**: search repos, fetch wiki content, ask questions with conversation history
-- **Multiple transports**: stdio (default), Streamable HTTP, SSE
-- **NLP repo resolution**: natural-language input → GitHub search → `owner/repo` (via wink-nlp)
-- **Retry with exponential backoff**: configurable retries for resilient API calls
-- **Structured errors**: typed error codes (`VALIDATION`, `RPC_FAIL`, `TIMEOUT`, `NLP_RESOLVE_FAIL`)
-- **Response metadata**: byte count and elapsed time on every response
-- **Docker support**: multi-stage Alpine build
-- **Claude Code skill**: prompt templates, workflow chains, error handling guide
+[🇷🇺 Русский](README.ru.md) | **🇬🇧 English**
 
-## Usage
+<br />
 
-Prompts you can use in any MCP-compatible client:
+*MCP server that connects any AI assistant to [codewiki.google](https://codewiki.google) — AI-generated wiki documentation for open-source repositories.*
 
-```
-codewiki fetch how routing works in Next.js
-```
+</div>
 
-```
-codewiki search state management libraries
-```
+---
 
-```
-codewiki ask how does React fiber reconciler work?
-```
+## 📖 Overview
 
-Fetch complete documentation:
-```
-codewiki fetch vercel/next.js
-codewiki fetch https://github.com/fastify/fastify
-```
+**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.
 
-Get structured pages:
-```
-codewiki fetch pages tailwindlabs/tailwindcss
-```
+---
 
-Ask with natural language:
-```
-codewiki ask fastify how to add authentication?
-```
+## ✨ 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
+---
+
+## 🚀 Quick Start
 
 ### Using npx (no install)
 
@@ -58,31 +54,26 @@ npx -y codewiki-mcp@latest
 ### From source
 
 ```bash
-git clone https://github.com/nicholasxwang/codewiki-mcp.git
+git clone https://github.com/izzzzzi/codewiki-mcp.git
 cd codewiki-mcp
 npm install
 npm run build
 ```
 
-### stdio (default)
+### Transports
 
 ```bash
+# stdio (default)
 node dist/cli.js
-```
 
-### HTTP
-
-```bash
+# Streamable HTTP
 node dist/cli.js --http --port 3000
-```
 
-### SSE
-
-```bash
+# SSE
 node dist/cli.js --sse --port 3001
 ```
 
-### Docker
+### 🐳 Docker
 
 ```bash
 docker build -t codewiki-mcp .
@@ -101,11 +92,14 @@ docker run -p 3000:3000 \
   codewiki-mcp --http
 ```
 
-## MCP Client Configuration
+---
 
-### Cursor
+## 🔧 MCP Client Configuration
 
-Add to `.cursor/mcp.json` (or use the included one):
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json`:
 
 ```json
 {
@@ -118,7 +112,10 @@ Add to `.cursor/mcp.json` (or use the included one):
 }
 ```
 
-### Claude Desktop
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
 
 Add to `claude_desktop_config.json`:
 
@@ -133,13 +130,19 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-### Claude Code
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
 
 ```bash
 claude mcp add codewiki-mcp -- npx -y codewiki-mcp@latest
 ```
 
-### Windsurf
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
 
 Add to your Windsurf MCP config:
 
@@ -154,7 +157,10 @@ Add to your Windsurf MCP config:
 }
 ```
 
-### VS Code (Copilot)
+</details>
+
+<details>
+<summary><b>VS Code (Copilot)</b></summary>
 
 Add to `.vscode/mcp.json`:
 
@@ -169,7 +175,10 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
-### Local development config
+</details>
+
+<details>
+<summary><b>Local development</b></summary>
 
 ```json
 {
@@ -182,39 +191,83 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
-## MCP Tools
+</details>
+
+---
+
+## 💡 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?
+```
+
+---
 
-### codewiki_search_repos
+## 🛠️ MCP Tools
+
+### 🔍 codewiki_search_repos
 
 Search repositories indexed by codewiki.google.
 
 | Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | yes | — | Search query |
-| `limit` | number | no | 10 | Max results (1–50) |
+|-----------|------|:--------:|---------|-------------|
+| `query` | string | ✅ | — | Search query |
+| `limit` | number | — | 10 | Max results (1–50) |
 
-### codewiki_fetch_repo
+### 📄 codewiki_fetch_repo
 
 Fetch generated wiki content for a repository.
 
 | Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `repo` | string | yes | — | `owner/repo`, GitHub URL, or natural-language query |
-| `mode` | string | no | `"aggregate"` | `"aggregate"` — full markdown; `"pages"` — structured JSON |
+|-----------|------|:--------:|---------|-------------|
+| `repo` | string | ✅ | — | `owner/repo`, GitHub URL, or natural-language query |
+| `mode` | string | — | `"aggregate"` | `"aggregate"` — full markdown; `"pages"` — structured JSON |
 
-### codewiki_ask_repo
+### 💬 codewiki_ask_repo
 
 Ask a natural-language question about a repository.
 
 | Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `repo` | string | yes | — | Repository identifier (same formats as fetch) |
-| `question` | string | yes | — | Question about the repo |
-| `history` | array | no | `[]` | Conversation history `[{role, content}]` (max 20) |
+|-----------|------|:--------:|---------|-------------|
+| `repo` | string | ✅ | — | Repository identifier (same formats as fetch) |
+| `question` | string | ✅ | — | Question about the repo |
+| `history` | array | — | `[]` | Conversation history `[{role, content}]` (max 20) |
+
+---
 
-## Response Format
+## 📊 Response Format
 
-### Success — Search
+<details>
+<summary><b>✅ Success — Search</b></summary>
 
 ```json
 {
@@ -236,7 +289,10 @@ Ask a natural-language question about a repository.
 }
 ```
 
-### Success — Fetch (pages mode)
+</details>
+
+<details>
+<summary><b>✅ Success — Fetch (pages mode)</b></summary>
 
 ```json
 {
@@ -259,7 +315,10 @@ Ask a natural-language question about a repository.
 }
 ```
 
-### Success — Ask
+</details>
+
+<details>
+<summary><b>✅ Success — Ask</b></summary>
 
 ```json
 {
@@ -271,7 +330,10 @@ Ask a natural-language question about a repository.
 }
 ```
 
-### Error Response
+</details>
+
+<details>
+<summary><b>❌ Error Response</b></summary>
 
 ```json
 {
@@ -284,47 +346,20 @@ Ask a natural-language question about a repository.
 }
 ```
 
-### Direct API Calls (HTTP transport)
+Error codes: `VALIDATION`, `RPC_FAIL`, `TIMEOUT`, `NLP_RESOLVE_FAIL`
 
-```bash
-# Start server
-node dist/cli.js --http --port 3000
+</details>
 
-# Search
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "tools/call",
-    "params": {
-      "name": "codewiki_search_repos",
-      "arguments": { "query": "fastify", "limit": 5 }
-    }
-  }'
-
-# Fetch wiki
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 2,
-    "method": "tools/call",
-    "params": {
-      "name": "codewiki_fetch_repo",
-      "arguments": { "repo": "fastify/fastify", "mode": "pages" }
-    }
-  }'
-```
+---
 
-## How It Works
+## ⚙️ How It Works
 
 ### Data Flow
 
 ```
-Claude Code → MCP protocol → codewiki-mcp → HTTPS → codewiki.google
-                                                          ↓
-Claude Code ← MCP protocol ← codewiki-mcp ← JSON  ← Google RPC API
+AI Assistant → MCP protocol → codewiki-mcp → HTTPS → codewiki.google
+                                                            ↓
+AI Assistant ← MCP protocol ← codewiki-mcp ← JSON  ← Google RPC API
 ```
 
 ### Google Batchexecute RPC
@@ -337,11 +372,14 @@ codewiki.google uses Google's internal **batchexecute** RPC format (not REST, no
 4. Parses `wrb.fr` frames and extracts the typed payload
 
 Each tool maps to an RPC ID:
-- `vyWDAf` — search
-- `VSX6ub` — fetch wiki
-- `EgIxfe` — ask question
 
-### NLP Repo Resolution
+| Tool | RPC ID |
+|------|:------:|
+| 🔍 Search | `vyWDAf` |
+| 📄 Fetch | `VSX6ub` |
+| 💬 Ask | `EgIxfe` |
+
+### 🧠 NLP Repo Resolution
 
 Users can type natural language instead of `owner/repo`:
 
@@ -353,20 +391,20 @@ Users can type natural language instead of `owner/repo`:
   → normalizeRepoInput("fastify/fastify") → URL for codewiki
 ```
 
-### Retry with Exponential Backoff
+### 🔄 Retry with Exponential Backoff
 
-On 5xx errors or timeouts, the client retries automatically:
+| Attempt | Delay |
+|:-------:|------:|
+| 0 | immediate |
+| 1 | 250ms |
+| 2 | 500ms |
+| 3 | 1000ms |
 
-```
-Attempt 0: immediate
-Attempt 1: after 250ms
-Attempt 2: after 500ms
-Attempt 3: after 1000ms
-```
+> 4xx errors (client errors) are never retried.
 
-4xx errors (client errors) are never retried.
+---
 
-## CLI
+## 🖥️ CLI
 
 ```
 codewiki-mcp [options]
@@ -379,7 +417,9 @@ Options:
   --help, -h       Show help
 ```
 
-## Configuration
+---
+
+## ⚡ Configuration
 
 Environment variables:
 
@@ -399,19 +439,9 @@ CODEWIKI_MAX_RETRIES=5
 GITHUB_TOKEN=ghp_your_token
 ```
 
-## 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/
-```
-
-## Project Structure
+## 📁 Project Structure
 
 ```
 src/
@@ -433,22 +463,31 @@ src/
     └── askRepo.ts          # codewiki_ask_repo
 ```
 
-## Troubleshooting
+---
 
-### Permission Denied
+## ❓ Troubleshooting
+
+<details>
+<summary><b>Permission Denied</b></summary>
 
 ```bash
 chmod +x ./node_modules/.bin/codewiki-mcp
 ```
 
-### Connection Refused (HTTP/SSE)
+</details>
+
+<details>
+<summary><b>Connection Refused (HTTP/SSE)</b></summary>
 
 ```bash
 # Check if port is in use
 lsof -i :3000
 ```
 
-### Timeout Errors
+</details>
+
+<details>
+<summary><b>Timeout Errors</b></summary>
 
 For large repositories, increase the timeout:
 
@@ -456,7 +495,10 @@ For large repositories, increase the timeout:
 CODEWIKI_REQUEST_TIMEOUT=60000 node dist/cli.js
 ```
 
-### NLP Resolution Fails
+</details>
+
+<details>
+<summary><b>NLP Resolution Fails</b></summary>
 
 If natural-language input doesn't resolve, use explicit format:
 
@@ -469,7 +511,25 @@ https://github.com/fastify/fastify
 
 Set `GITHUB_TOKEN` to avoid GitHub API rate limits for unauthenticated requests.
 
-## Contributing
+</details>
+
+---
+
+## 🧑‍💻 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:
 
@@ -479,6 +539,8 @@ Contributions are welcome! Please:
 4. Run `npm run typecheck && npm run test` before submitting
 5. Open a Pull Request
 
-## License
+---
+
+## 📄 License
 
-MIT
+[MIT](LICENSE) © codewiki-mcp contributors