codewiki-mcp 1.0.0

package/src/tools/askRepo.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { AskHistoryItem, CodeWikiClient } from '../lib/codewikiClient.js'
+import type { CodeWikiConfig } from '../lib/config.js'
+import { formatMcpError } from '../lib/errors.js'
+import { resolveRepoInput } from '../lib/repo.js'
+import { AskRepoInput } from '../schemas.js'
+
+export function registerAskRepoTool(mcp: McpServer, client: CodeWikiClient, config?: CodeWikiConfig): void {
+  mcp.tool(
+    'codewiki_ask_repo',
+    'Ask a natural-language question about a repository indexed in codewiki.google',
+    AskRepoInput.shape,
+    async (rawInput) => {
+      const parsed = AskRepoInput.safeParse(rawInput)
+      if (!parsed.success) {
+        return {
+          content: [{ type: 'text', text: `Invalid arguments: ${parsed.error.message}` }],
+          isError: true,
+        }
+      }
+
+      try {
+        const { repo, question, history } = parsed.data
+        const resolved = await resolveRepoInput(repo, config)
+        const { data: answer, meta } = await client.askRepository(resolved.repoUrl, question, history as AskHistoryItem[] | undefined)
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ answer, meta }, null, 2),
+          }],
+        }
+      } catch (err) {
+        return formatMcpError(err)
+      }
+    },
+  )
+}

package/src/tools/fetchRepo.ts

@@ -0,0 +1,74 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CodeWikiClient, WikiSection } from '../lib/codewikiClient.js'
+import type { CodeWikiConfig } from '../lib/config.js'
+import { formatMcpError } from '../lib/errors.js'
+import { resolveRepoInput } from '../lib/repo.js'
+import { FetchRepoInput } from '../schemas.js'
+
+function toSectionMarkdown(section: WikiSection): string {
+  const depth = Math.max(1, Math.min(6, section.level))
+  const heading = '#'.repeat(depth)
+  const body = section.markdown || section.summary || ''
+  return `${heading} ${section.title}\n\n${body}`.trim()
+}
+
+export function registerFetchRepoTool(mcp: McpServer, client: CodeWikiClient, config?: CodeWikiConfig): void {
+  mcp.tool(
+    'codewiki_fetch_repo',
+    'Fetch generated wiki content for a repository from codewiki.google',
+    FetchRepoInput.shape,
+    async (rawInput) => {
+      const parsed = FetchRepoInput.safeParse(rawInput)
+      if (!parsed.success) {
+        return {
+          content: [{ type: 'text', text: `Invalid arguments: ${parsed.error.message}` }],
+          isError: true,
+        }
+      }
+
+      try {
+        const { repo, mode } = parsed.data
+        const resolved = await resolveRepoInput(repo, config)
+        const { data: result, meta } = await client.fetchRepository(resolved.repoUrl)
+
+        if (mode === 'pages') {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                repo: result.repo,
+                commit: result.commit,
+                canonicalUrl: result.canonicalUrl,
+                pages: result.sections.map(section => ({
+                  title: section.title,
+                  level: section.level,
+                  anchor: section.anchor,
+                  markdown: section.markdown,
+                  diagramCount: section.diagramCount,
+                })),
+                meta,
+              }, null, 2),
+            }],
+          }
+        }
+
+        const aggregate = result.sections.map(toSectionMarkdown).join('\n\n')
+        const preface = [
+          `Repository: ${result.repo}`,
+          `Commit: ${result.commit ?? 'unknown'}`,
+          result.canonicalUrl ? `Canonical URL: ${result.canonicalUrl}` : null,
+          `Response: ${meta.totalBytes} bytes in ${meta.totalElapsedMs}ms`,
+        ].filter(Boolean).join('\n')
+
+        return {
+          content: [{
+            type: 'text',
+            text: `${preface}\n\n${aggregate}`.trim(),
+          }],
+        }
+      } catch (err) {
+        return formatMcpError(err)
+      }
+    },
+  )
+}

package/src/tools/searchRepos.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CodeWikiClient } from '../lib/codewikiClient.js'
+import { formatMcpError } from '../lib/errors.js'
+import { SearchReposInput } from '../schemas.js'
+
+export function registerSearchReposTool(mcp: McpServer, client: CodeWikiClient): void {
+  mcp.tool(
+    'codewiki_search_repos',
+    'Search repositories indexed by codewiki.google',
+    SearchReposInput.shape,
+    async (rawInput) => {
+      const parsed = SearchReposInput.safeParse(rawInput)
+      if (!parsed.success) {
+        return {
+          content: [{ type: 'text', text: `Invalid arguments: ${parsed.error.message}` }],
+          isError: true,
+        }
+      }
+
+      try {
+        const { query, limit } = parsed.data
+        const { data: items, meta } = await client.searchRepositories(query, limit)
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              query,
+              count: items.length,
+              items,
+              meta,
+            }, null, 2),
+          }],
+        }
+      } catch (err) {
+        return formatMcpError(err)
+      }
+    },
+  )
+}

package/tests/batchexecute.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { extractRpcPayload, extractWrbFrames } from '../src/lib/batchexecute.js'
+
+describe('batchexecute parser', () => {
+  it('extracts wrb.fr frame with XSSI prefix and length lines', () => {
+    const payload = [[['owner/repo', null, 3]]]
+    const payloadJson = JSON.stringify(payload)
+    const wrbLine = JSON.stringify([[
+      'wrb.fr',
+      'vyWDAf',
+      payloadJson,
+      null,
+      null,
+      null,
+      'generic',
+    ]])
+
+    const text = `)]}'\n\n${wrbLine.length}\n${wrbLine}\n26\n[[\"e\",4,null,null,0]]\n`
+
+    const frames = extractWrbFrames(text)
+    expect(frames).toHaveLength(1)
+    expect(frames[0].rpcId).toBe('vyWDAf')
+    expect(frames[0].payload).toEqual(payload)
+  })
+
+  it('extracts specific RPC payload when multiple frames exist', () => {
+    const firstPayload = ['one']
+    const secondPayload = ['two']
+    const line = JSON.stringify([
+      ['wrb.fr', 'vyWDAf', JSON.stringify(firstPayload), null, null, null, 'generic'],
+      ['wrb.fr', 'VSX6ub', JSON.stringify(secondPayload), null, null, null, 'generic'],
+    ])
+
+    const text = `)]}'\n${line}`
+
+    expect(extractRpcPayload(text, 'VSX6ub')).toEqual(secondPayload)
+  })
+
+  it('throws when no wrb.fr frames found', () => {
+    expect(() => extractWrbFrames(`)]}'\n42\n{}`)).toThrow('No wrb.fr frames found')
+  })
+})

package/tests/client.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { CodeWikiClient } from '../src/lib/codewikiClient.js'
+
+function makeRpcResponse(rpcId: string, payload: unknown): string {
+  const wrbLine = JSON.stringify([[
+    'wrb.fr',
+    rpcId,
+    JSON.stringify(payload),
+    null,
+    null,
+    null,
+    'generic',
+  ]])
+  return `)]}'\n\n${wrbLine}`
+}
+
+describe('CodeWikiClient', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('searchRepositories parses vyWDAf result', async () => {
+    const payload = [[
+      [
+        'aiogram/aiogram',
+        null,
+        3,
+        [null, 'https://github.com/aiogram/aiogram'],
+        [123, 456],
+        ['desc', 'https://img', 555, 'aiogram/aiogram'],
+      ],
+    ]]
+
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(makeRpcResponse('vyWDAf', payload), { status: 200 })))
+
+    const client = new CodeWikiClient()
+    const { data: result, meta } = await client.searchRepositories('aiogram', 5)
+
+    expect(result).toHaveLength(1)
+    expect(result[0].fullName).toBe('aiogram/aiogram')
+    expect(result[0].url).toBe('https://github.com/aiogram/aiogram')
+    expect(result[0].description).toBe('desc')
+    expect(meta.totalBytes).toBeGreaterThan(0)
+    expect(meta.totalElapsedMs).toBeGreaterThanOrEqual(0)
+  })
+
+  it('fetchRepository parses VSX6ub result and sections', async () => {
+    const payload = [
+      [
+        ['aiogram/aiogram', 'abc123'],
+        [
+          ['Overview', 1, 'summary text', null, 'markdown fallback', 'markdown main', 1, [[1]], null, '#overview'],
+          ['Details', 2, null, null, 'details markdown'],
+        ],
+        null,
+      ],
+      [[null, 'https://github.com/aiogram/aiogram'], true, 3],
+    ]
+
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(makeRpcResponse('VSX6ub', payload), { status: 200 })))
+
+    const client = new CodeWikiClient()
+    const { data: result, meta } = await client.fetchRepository('aiogram/aiogram')
+
+    expect(result.repo).toBe('aiogram/aiogram')
+    expect(result.commit).toBe('abc123')
+    expect(result.canonicalUrl).toBe('https://github.com/aiogram/aiogram')
+    expect(result.sections).toHaveLength(2)
+    expect(result.sections[0].title).toBe('Overview')
+    expect(result.sections[0].markdown).toBe('markdown main')
+    expect(result.sections[0].anchor).toBe('#overview')
+    expect(result.sections[1].level).toBe(2)
+    expect(meta.totalBytes).toBeGreaterThan(0)
+  })
+
+  it('askRepository parses EgIxfe answer', async () => {
+    const payload = ['Final answer text']
+
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(makeRpcResponse('EgIxfe', payload), { status: 200 })))
+
+    const client = new CodeWikiClient()
+    const { data: answer, meta } = await client.askRepository('https://github.com/aiogram/aiogram', 'what is this?')
+
+    expect(answer).toBe('Final answer text')
+    expect(meta.totalBytes).toBeGreaterThan(0)
+  })
+
+  it('throws CodeWikiError on non-ok HTTP response', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('bad', { status: 500 })))
+
+    const client = new CodeWikiClient({ maxRetries: 0 })
+    await expect(client.searchRepositories('aiogram', 5)).rejects.toThrow('CodeWiki RPC vyWDAf failed with status 500')
+  })
+
+  it('retries on server error', async () => {
+    const mockFetch = vi.fn()
+      .mockResolvedValueOnce(new Response('bad', { status: 500 }))
+      .mockResolvedValueOnce(new Response(makeRpcResponse('vyWDAf', [[]]), { status: 200 }))
+
+    vi.stubGlobal('fetch', mockFetch)
+
+    const client = new CodeWikiClient({ maxRetries: 1, retryDelay: 1 })
+    const { data } = await client.searchRepositories('test', 1)
+
+    expect(mockFetch).toHaveBeenCalledTimes(2)
+    expect(data).toEqual([])
+  })
+
+  it('does not retry on 4xx errors', async () => {
+    const mockFetch = vi.fn()
+      .mockResolvedValue(new Response('bad', { status: 400 }))
+
+    vi.stubGlobal('fetch', mockFetch)
+
+    const client = new CodeWikiClient({ maxRetries: 3, retryDelay: 1 })
+    await expect(client.searchRepositories('test', 1)).rejects.toThrow('failed with status 400')
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('creates client from config', () => {
+    const client = CodeWikiClient.fromConfig({
+      baseUrl: 'https://custom.host',
+      requestTimeout: 5000,
+      maxRetries: 5,
+      retryDelay: 100,
+    })
+    expect(client).toBeInstanceOf(CodeWikiClient)
+  })
+})

package/tests/errors.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import { loadConfig } from '../src/lib/config.js'
+import { CodeWikiError, formatMcpError } from '../src/lib/errors.js'
+
+describe('CodeWikiError', () => {
+  it('creates error with code and message', () => {
+    const err = new CodeWikiError('RPC_FAIL', 'request failed')
+    expect(err.name).toBe('CodeWikiError')
+    expect(err.code).toBe('RPC_FAIL')
+    expect(err.message).toBe('request failed')
+    expect(err.statusCode).toBeUndefined()
+    expect(err.rpcId).toBeUndefined()
+  })
+
+  it('creates error with optional fields', () => {
+    const err = new CodeWikiError('TIMEOUT', 'timed out', {
+      statusCode: 504,
+      rpcId: 'vyWDAf',
+    })
+    expect(err.code).toBe('TIMEOUT')
+    expect(err.statusCode).toBe(504)
+    expect(err.rpcId).toBe('vyWDAf')
+  })
+
+  it('preserves cause', () => {
+    const cause = new Error('original')
+    const err = new CodeWikiError('RPC_FAIL', 'wrapped', { cause })
+    expect((err as any).cause).toBe(cause)
+  })
+
+  it('is an instance of Error', () => {
+    const err = new CodeWikiError('VALIDATION', 'bad input')
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(CodeWikiError)
+  })
+})
+
+describe('formatMcpError', () => {
+  it('formats CodeWikiError as structured envelope', () => {
+    const err = new CodeWikiError('RPC_FAIL', 'server error', {
+      statusCode: 500,
+      rpcId: 'VSX6ub',
+    })
+    const result = formatMcpError(err)
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error.code).toBe('RPC_FAIL')
+    expect(parsed.error.message).toBe('server error')
+    expect(parsed.error.statusCode).toBe(500)
+    expect(parsed.error.rpcId).toBe('VSX6ub')
+  })
+
+  it('formats plain Error as RPC_FAIL envelope', () => {
+    const err = new Error('something broke')
+    const result = formatMcpError(err)
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error.code).toBe('RPC_FAIL')
+    expect(parsed.error.message).toBe('something broke')
+  })
+
+  it('formats string error', () => {
+    const result = formatMcpError('raw string error')
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error.code).toBe('RPC_FAIL')
+    expect(parsed.error.message).toBe('raw string error')
+  })
+
+  it('omits optional fields when not present', () => {
+    const err = new CodeWikiError('VALIDATION', 'bad')
+    const result = formatMcpError(err)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error.rpcId).toBeUndefined()
+    expect(parsed.error.statusCode).toBeUndefined()
+  })
+})
+
+describe('loadConfig', () => {
+  it('returns defaults when no env vars set', () => {
+    const config = loadConfig({})
+    expect(config.baseUrl).toBe('https://codewiki.google')
+    expect(config.requestTimeout).toBe(30_000)
+    expect(config.maxRetries).toBe(3)
+    expect(config.retryDelay).toBe(250)
+    expect(config.githubToken).toBeUndefined()
+  })
+
+  it('reads env vars when set', () => {
+    const config = loadConfig({
+      CODEWIKI_BASE_URL: 'https://custom.host',
+      CODEWIKI_REQUEST_TIMEOUT: '5000',
+      CODEWIKI_MAX_RETRIES: '5',
+      CODEWIKI_RETRY_DELAY: '100',
+      GITHUB_TOKEN: 'ghp_test123',
+    })
+    expect(config.baseUrl).toBe('https://custom.host')
+    expect(config.requestTimeout).toBe(5000)
+    expect(config.maxRetries).toBe(5)
+    expect(config.retryDelay).toBe(100)
+    expect(config.githubToken).toBe('ghp_test123')
+  })
+
+  it('falls back to defaults for invalid numbers', () => {
+    const config = loadConfig({
+      CODEWIKI_REQUEST_TIMEOUT: 'not-a-number',
+      CODEWIKI_MAX_RETRIES: '-1',
+      CODEWIKI_RETRY_DELAY: '0',
+    })
+    expect(config.requestTimeout).toBe(30_000)
+    expect(config.maxRetries).toBe(3)
+    expect(config.retryDelay).toBe(250)
+  })
+
+  it('treats empty GITHUB_TOKEN as undefined', () => {
+    const config = loadConfig({ GITHUB_TOKEN: '' })
+    expect(config.githubToken).toBeUndefined()
+  })
+})

package/tests/extractKeyword.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { extractKeyword } from '../src/lib/extractKeyword.js'
+
+describe('extractKeyword', () => {
+  it('extracts noun from simple query', () => {
+    const result = extractKeyword('find the fastify framework')
+    expect(result).toBe('fastify')
+  })
+
+  it('extracts proper noun', () => {
+    const result = extractKeyword('tell me about React')
+    expect(result).toBe('React')
+  })
+
+  it('filters stop words like "repository"', () => {
+    const result = extractKeyword('show me the repository for express')
+    expect(result).toBe('express')
+  })
+
+  it('returns null for all stop words', () => {
+    const result = extractKeyword('show me the')
+    expect(result).toBeNull()
+  })
+
+  it('handles single word input', () => {
+    const result = extractKeyword('tensorflow')
+    expect(result).toBe('tensorflow')
+  })
+
+  it('returns null for empty string', () => {
+    const result = extractKeyword('')
+    expect(result).toBeNull()
+  })
+})

package/tests/resolveRepo.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveRepoFromGitHub } from '../src/lib/resolveRepo.js'
+import { resolveRepoInput } from '../src/lib/repo.js'
+
+describe('resolveRepoFromGitHub', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('resolves keyword to full_name from GitHub API', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(
+      JSON.stringify({ items: [{ full_name: 'fastify/fastify' }] }),
+      { status: 200 },
+    )))
+
+    const result = await resolveRepoFromGitHub('fastify', { requestTimeout: 5000 })
+    expect(result).toBe('fastify/fastify')
+  })
+
+  it('throws NLP_RESOLVE_FAIL when no items found', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(
+      JSON.stringify({ items: [] }),
+      { status: 200 },
+    )))
+
+    await expect(
+      resolveRepoFromGitHub('nonexistent-xyz-abc', { requestTimeout: 5000 }),
+    ).rejects.toThrow('No GitHub repository found')
+  })
+
+  it('throws NLP_RESOLVE_FAIL on non-ok response', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('rate limited', { status: 403 })))
+
+    await expect(
+      resolveRepoFromGitHub('test', { requestTimeout: 5000 }),
+    ).rejects.toThrow('GitHub search failed with status 403')
+  })
+
+  it('includes auth header when token provided', async () => {
+    const mockFetch = vi.fn(async () => new Response(
+      JSON.stringify({ items: [{ full_name: 'owner/repo' }] }),
+      { status: 200 },
+    ))
+    vi.stubGlobal('fetch', mockFetch)
+
+    await resolveRepoFromGitHub('test', { requestTimeout: 5000, githubToken: 'ghp_test' })
+
+    const callArgs = mockFetch.mock.calls[0]
+    const headers = callArgs[1]?.headers as Record<string, string>
+    expect(headers['Authorization']).toBe('Bearer ghp_test')
+  })
+})
+
+describe('resolveRepoInput', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('resolves URL synchronously', async () => {
+    const result = await resolveRepoInput('https://github.com/fastify/fastify')
+    expect(result.repoPath).toBe('fastify/fastify')
+    expect(result.host).toBe('github.com')
+  })
+
+  it('resolves owner/repo synchronously', async () => {
+    const result = await resolveRepoInput('fastify/fastify')
+    expect(result.repoPath).toBe('fastify/fastify')
+  })
+
+  it('resolves natural language via NLP + GitHub', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(
+      JSON.stringify({ items: [{ full_name: 'fastify/fastify' }] }),
+      { status: 200 },
+    )))
+
+    const result = await resolveRepoInput('the fastify web framework')
+    expect(result.repoPath).toBe('fastify/fastify')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    globals: true,
+    clearMocks: true,
+  },
+})