codewiki-mcp 1.0.1 → 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/package.json

@@ -1,11 +1,33 @@
 {
   "name": "codewiki-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
+  "mcpName": "io.github.izzzzzi/codewiki-mcp",
   "description": "MCP server for codewiki.google",
   "type": "module",
+  "main": "dist/index.js",
   "bin": {
     "codewiki-mcp": "dist/cli.js"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "codewiki",
+    "documentation",
+    "github",
+    "ai",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/izzzzzi/codewiki-mcp.git"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/izzzzzi/codewiki-mcp",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",

package/.claude/skills/codewiki.md

@@ -1,186 +0,0 @@
----
-name: codewiki
-description: Research any open-source repository via codewiki.google — search, fetch wiki docs, ask questions
-tools: ["codewiki_search_repos", "codewiki_fetch_repo", "codewiki_ask_repo"]
----
-
-# CodeWiki MCP — Skill Guide
-
-## Available Tools
-
-### codewiki_search_repos
-Search repositories indexed by codewiki.google.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | string | yes | Search query (library name, keyword, description) |
-| `limit` | number | no | Max results (1-50, default 10) |
-
-**Returns**: JSON with `query`, `count`, `items[]` (each with `fullName`, `url`, `description`, `avatarUrl`, `extraScore`), and `meta` (totalBytes, totalElapsedMs).
-
-### codewiki_fetch_repo
-Fetch generated wiki content for a repository.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `repo` | string | yes | Repository identifier: `owner/repo`, full GitHub URL, or natural-language query (NLP resolved) |
-| `mode` | string | no | `"aggregate"` (default) — full markdown; `"pages"` — structured JSON per section |
-
-**Returns**:
-- **aggregate mode**: Markdown text with preface (repo, commit, canonical URL, response meta)
-- **pages mode**: JSON with `repo`, `commit`, `canonicalUrl`, `pages[]` (title, level, anchor, markdown, diagramCount), and `meta`
-
-### codewiki_ask_repo
-Ask a natural-language question about a repository.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `repo` | string | yes | Repository identifier (same formats as fetch) |
-| `question` | string | yes | Natural-language question about the repo |
-| `history` | array | no | Conversation history: `[{role: "user"|"assistant", content: "..."}]` (max 20) |
-
-**Returns**: JSON with `answer` (string) and `meta` (totalBytes, totalElapsedMs).
-
----
-
-## Prompt Templates
-
-### Study a project's architecture
-```
-1. codewiki_search_repos(query: "<project name>")
-   → find the exact owner/repo
-2. codewiki_fetch_repo(repo: "<owner/repo>", mode: "aggregate")
-   → read the full wiki to understand architecture
-3. codewiki_ask_repo(repo: "<owner/repo>", question: "What are the main architectural patterns and components?")
-   → deep-dive into architecture
-```
-
-### Find how a feature is implemented
-```
-codewiki_ask_repo(
-  repo: "<owner/repo>",
-  question: "How is <feature X> implemented? Show the key modules and data flow."
-)
-```
-
-### Compare approaches in two repos
-```
-1. codewiki_fetch_repo(repo: "<owner1/repo1>", mode: "pages")
-2. codewiki_fetch_repo(repo: "<owner2/repo2>", mode: "pages")
-3. Compare the architectural approaches, patterns, and trade-offs
-```
-
-### Quick library overview
-```
-1. codewiki_search_repos(query: "<library>")
-   → confirm the right repo
-2. codewiki_fetch_repo(repo: "<owner/repo>", mode: "pages")
-   → get structured sections
-3. Summarize: purpose, key features, getting started, API surface
-```
-
-### Explore a topic across repos
-```
-1. codewiki_search_repos(query: "<topic>", limit: 5)
-   → find top repos for the topic
-2. For each interesting repo:
-   codewiki_ask_repo(repo: "<repo>", question: "Summarize the approach to <topic>")
-3. Synthesize findings across repos
-```
-
----
-
-## Workflow Chains
-
-### Deep Research Chain
-**Goal**: Thorough understanding of a project
-
-1. **Search** → `codewiki_search_repos` to find the repo and confirm its full name
-2. **Fetch overview** → `codewiki_fetch_repo(mode: "aggregate")` to read the full wiki
-3. **Ask specific questions** → `codewiki_ask_repo` for deep-dives into specific areas
-4. **Follow up** → Use `history` parameter to maintain context across questions
-
-### Comparison Chain
-**Goal**: Compare two or more implementations
-
-1. **Fetch all** → `codewiki_fetch_repo(mode: "pages")` for each repo
-2. **Identify patterns** → Extract architectural sections from each
-3. **Ask targeted questions** → `codewiki_ask_repo` about specific differences
-
-### Migration Research Chain
-**Goal**: Understand a library for migration
-
-1. **Search** → Find source and target libraries
-2. **Fetch both** → Get wiki content for both
-3. **Ask migration questions** → "What are the key API differences between X and Y?"
-4. **Ask compatibility** → "What breaking changes should I watch for?"
-
----
-
-## Error Handling
-
-| Error Code | Meaning | Action |
-|------------|---------|--------|
-| `VALIDATION` | Invalid input parameters | Check parameter types and required fields |
-| `RPC_FAIL` | CodeWiki API call failed | Retry with different query; check if repo exists on codewiki.google |
-| `TIMEOUT` | Request timed out | Try again; for large repos, use `mode: "pages"` to get structured data |
-| `NLP_RESOLVE_FAIL` | Could not resolve natural-language input to a repo | Use explicit `owner/repo` format instead |
-
-When you receive an error:
-1. Parse the error envelope: `{ error: { code, message, rpcId?, statusCode? } }`
-2. If `RPC_FAIL` with `statusCode: 404` → repo not indexed, suggest searching first
-3. If `TIMEOUT` → simplify query or try mode: "pages" for fetch
-4. If `NLP_RESOLVE_FAIL` → ask user for the exact repo name
-
----
-
-## Conversation History Tips
-
-The `history` parameter in `codewiki_ask_repo` enables multi-turn conversations:
-
-```json
-{
-  "repo": "facebook/react",
-  "question": "How does the fiber reconciler differ?",
-  "history": [
-    {"role": "user", "content": "What is the rendering pipeline?"},
-    {"role": "assistant", "content": "React's rendering pipeline consists of..."}
-  ]
-}
-```
-
-**Best practices**:
-- Keep history under 20 entries for optimal performance
-- Include only relevant prior Q&A pairs
-- Summarize long assistant responses in history to save tokens
-- Start a new conversation (no history) when changing topics
-
----
-
-## Examples
-
-### Example 1: Quick repo lookup
-**User**: "What does the fastify framework do?"
-```
-codewiki_search_repos(query: "fastify")
-→ finds fastify/fastify
-codewiki_ask_repo(repo: "fastify/fastify", question: "What is Fastify and what are its key features?")
-→ comprehensive answer
-```
-
-### Example 2: Architecture deep-dive
-**User**: "Explain how Next.js handles server-side rendering"
-```
-codewiki_fetch_repo(repo: "vercel/next.js", mode: "aggregate")
-→ full wiki content
-codewiki_ask_repo(repo: "vercel/next.js", question: "How does Next.js implement server-side rendering? Describe the request lifecycle.")
-→ detailed SSR explanation
-```
-
-### Example 3: Library comparison
-**User**: "Compare Express and Fastify"
-```
-codewiki_fetch_repo(repo: "expressjs/express", mode: "pages")
-codewiki_fetch_repo(repo: "fastify/fastify", mode: "pages")
-→ compare architectures, middleware patterns, performance approaches
-```

package/.cursor/mcp.json

@@ -1,9 +0,0 @@
-{
-  "mcpServers": {
-    "codewiki-mcp": {
-      "command": "node",
-      "args": ["dist/cli.js"],
-      "cwd": "."
-    }
-  }
-}

package/.dockerignore

@@ -1,10 +0,0 @@
-node_modules
-dist
-tests
-.git
-.gitignore
-*.md
-.claude
-.cursor
-coverage
-.DS_Store

package/.github/dependabot.yml

@@ -1,33 +0,0 @@
-version: 2
-
-updates:
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: weekly
-      day: monday
-    open-pull-requests-limit: 10
-    labels:
-      - dependencies
-    commit-message:
-      prefix: "chore(deps):"
-    groups:
-      dev-dependencies:
-        dependency-type: development
-        update-types:
-          - minor
-          - patch
-      production-dependencies:
-        dependency-type: production
-        update-types:
-          - patch
-
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-      day: monday
-    labels:
-      - ci
-    commit-message:
-      prefix: "ci:"

package/.github/workflows/ci.yml

@@ -1,42 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-
-      - run: npm ci
-      - run: npm run typecheck
-      - run: npm run build
-      - run: npm run test
-
-  docker:
-    runs-on: ubuntu-latest
-    needs: test
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Build Docker image
-        run: docker build -t codewiki-mcp .
-
-      - name: Verify CLI starts
-        run: docker run --rm codewiki-mcp --help

package/.github/workflows/release.yml

@@ -1,36 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-  id-token: write
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 22
-          cache: npm
-
-      - run: npm ci
-      - run: npm run typecheck
-      - run: npm run build
-      - run: npm run test
-
-      - name: Semantic Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npx semantic-release

package/.releaserc.json

@@ -1,16 +0,0 @@
-{
-  "branches": ["main"],
-  "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
-    "@semantic-release/changelog",
-    ["@semantic-release/npm", {
-      "npmPublish": true
-    }],
-    ["@semantic-release/git", {
-      "assets": ["CHANGELOG.md", "package.json", "package-lock.json"],
-      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
-    }],
-    "@semantic-release/github"
-  ]
-}

package/CHANGELOG.md

@@ -1,13 +0,0 @@
-## [1.0.1](https://github.com/izzzzzi/codewiki-mcp/compare/v1.0.0...v1.0.1) (2026-02-16)
-
-
-### Bug Fixes
-
-* **docs:** correct GitHub owner in badge URLs and clone links ([dbcaa48](https://github.com/izzzzzi/codewiki-mcp/commit/dbcaa48a8b3ebc99274fa8919ff1ee10ef89d4ac))
-
-# 1.0.0 (2026-02-16)
-
-
-### Features
-
-* codewiki-mcp v0.2.0 — full MCP server for codewiki.google ([4f4dec7](https://github.com/izzzzzi/codewiki-mcp/commit/4f4dec74e48821e8fe8193b73341fcad1e61449f))

package/Dockerfile

@@ -1,15 +0,0 @@
-FROM node:22-alpine AS builder
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY tsconfig.json ./
-COPY src/ src/
-RUN npm run build
-
-FROM node:22-alpine
-WORKDIR /app
-COPY --from=builder /app/package.json /app/package-lock.json ./
-RUN npm ci --omit=dev
-COPY --from=builder /app/dist/ dist/
-EXPOSE 3000
-ENTRYPOINT ["node", "dist/cli.js"]

package/src/cli.ts

@@ -1,67 +0,0 @@
-#!/usr/bin/env node
-
-import { parseArgs } from 'node:util'
-import { loadConfig } from './lib/config.js'
-import { createMcpServer, startServer, stopServer } from './server.js'
-
-const HELP = `
-codewiki-mcp — MCP server for codewiki.google
-
-Usage:
-  codewiki-mcp              Start with stdio transport (default)
-  codewiki-mcp --http       Start with Streamable HTTP transport
-  codewiki-mcp --sse        Start with SSE transport
-
-Options:
-  --http           Use Streamable HTTP transport
-  --sse            Use SSE transport
-  --port <number>  Port for HTTP/SSE (default: 3000)
-  --endpoint <str> URL endpoint (default: /mcp)
-  --help           Show this help message
-
-Environment variables:
-  CODEWIKI_BASE_URL         Base URL (default: https://codewiki.google)
-  CODEWIKI_REQUEST_TIMEOUT  Request timeout in ms (default: 30000)
-  CODEWIKI_MAX_RETRIES      Max retries (default: 3)
-  CODEWIKI_RETRY_DELAY      Base retry delay in ms (default: 250)
-  GITHUB_TOKEN              GitHub token for NLP repo resolution
-`.trim()
-
-async function main(): Promise<void> {
-  const { values } = parseArgs({
-    options: {
-      http: { type: 'boolean', default: false },
-      sse: { type: 'boolean', default: false },
-      port: { type: 'string', default: '3000' },
-      endpoint: { type: 'string', default: '/mcp' },
-      help: { type: 'boolean', short: 'h', default: false },
-    },
-    strict: true,
-  })
-
-  if (values.help) {
-    console.log(HELP)
-    process.exit(0)
-  }
-
-  const transport = values.http ? 'http' : values.sse ? 'sse' : 'stdio'
-  const port = Number.parseInt(values.port!, 10) || 3000
-  const endpoint = values.endpoint!
-
-  const config = loadConfig()
-  const mcp = createMcpServer(config)
-
-  const shutdown = async () => {
-    await stopServer()
-    process.exit(0)
-  }
-  process.on('SIGTERM', shutdown)
-  process.on('SIGINT', shutdown)
-
-  await startServer(mcp, { transport, port, endpoint })
-}
-
-main().catch((error) => {
-  console.error(error)
-  process.exit(1)
-})

package/src/index.ts

@@ -1,32 +0,0 @@
-// Library re-exports
-export { CodeWikiClient } from './lib/codewikiClient.js'
-export type {
-  CodeWikiClientOptions,
-  SearchRepoResult,
-  WikiSection,
-  FetchRepositoryResult,
-  AskHistoryItem,
-  ResponseMeta,
-  WithMeta,
-} from './lib/codewikiClient.js'
-
-export { CodeWikiError, formatMcpError } from './lib/errors.js'
-export type { ErrorCode, ErrorEnvelope } from './lib/errors.js'
-
-export { loadConfig } from './lib/config.js'
-export type { CodeWikiConfig } from './lib/config.js'
-
-export { normalizeRepoInput, resolveRepoInput } from './lib/repo.js'
-export type { NormalizedRepo } from './lib/repo.js'
-
-export { extractKeyword } from './lib/extractKeyword.js'
-export { resolveRepoFromGitHub } from './lib/resolveRepo.js'
-
-export { createMcpServer, startServer, stopServer } from './server.js'
-export type { ServerOptions } from './server.js'
-
-export { SearchReposInput, FetchRepoInput, AskRepoInput } from './schemas.js'
-
-export { registerSearchReposTool } from './tools/searchRepos.js'
-export { registerFetchRepoTool } from './tools/fetchRepo.js'
-export { registerAskRepoTool } from './tools/askRepo.js'

package/src/lib/batchexecute.ts

@@ -1,72 +0,0 @@
-export interface WrbFrame {
-  rpcId: string
-  payload: unknown
-  rawPayload: unknown
-}
-
-const XSSI_PREFIX = ")]}'"
-
-function stripXssiPrefix(text: string): string {
-  const trimmed = text.trimStart()
-  if (trimmed.startsWith(XSSI_PREFIX)) {
-    return trimmed.slice(XSSI_PREFIX.length).trimStart()
-  }
-  return text
-}
-
-function safeJsonParse(input: string): unknown | undefined {
-  try {
-    return JSON.parse(input)
-  }
-  catch {
-    return undefined
-  }
-}
-
-function collectWrbFrames(node: unknown, out: WrbFrame[]): void {
-  if (!Array.isArray(node)) {
-    return
-  }
-
-  if (node.length >= 3 && node[0] === 'wrb.fr' && typeof node[1] === 'string') {
-    const rpcId = node[1]
-    const rawPayload = node[2]
-    const payload = typeof rawPayload === 'string'
-      ? (safeJsonParse(rawPayload) ?? rawPayload)
-      : rawPayload
-    out.push({ rpcId, payload, rawPayload })
-  }
-
-  for (const child of node) {
-    collectWrbFrames(child, out)
-  }
-}
-
-export function extractWrbFrames(responseText: string): WrbFrame[] {
-  const body = stripXssiPrefix(responseText)
-  const frames: WrbFrame[] = []
-
-  for (const rawLine of body.split(/\r?\n/)) {
-    const line = rawLine.trim()
-    if (!line.startsWith('[') || !line.endsWith(']')) {
-      continue
-    }
-
-    const parsed = safeJsonParse(line)
-    if (parsed !== undefined) {
-      collectWrbFrames(parsed, frames)
-    }
-  }
-
-  if (frames.length === 0) {
-    throw new Error('No wrb.fr frames found in batchexecute response')
-  }
-
-  return frames
-}
-
-export function extractRpcPayload(responseText: string, rpcId: string): unknown {
-  const frames = extractWrbFrames(responseText)
-  const match = frames.find(frame => frame.rpcId === rpcId) ?? frames[0]
-  return match.payload
-}