codewiki-mcp

Instructions

Implementation Reference

• src/tools/askRepo.ts:8-38 (handler)

  Main registration and handler function for codewiki_ask_repo tool. Registers the tool with MCP server, validates input using AskRepoInput schema, resolves repository input, calls the CodeWiki API, and returns the formatted response.

  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)
        }
      },
    )
  }

• src/schemas.ts:15-22 (schema)

  Zod schema definition for AskRepoInput, defining the input validation for the codewiki_ask_repo tool. Requires repo (string), question (string), and optional history array of role/content objects (max 20 items).

  export const AskRepoInput = z.object({
    repo: z.string().min(1),
    question: z.string().min(1),
    history: z.array(z.object({
      role: z.enum(['user', 'assistant']),
      content: z.string().min(1),
    })).max(20).optional(),
  })

• src/server.ts:27-40 (registration)

  Server initialization code that creates the MCP server, instantiates the CodeWikiClient, and calls registerAskRepoTool to register the codewiki_ask_repo tool along with other tools.

  export function createMcpServer(config: CodeWikiConfig): McpServer {
    const mcp = new McpServer({
      name: 'codewiki-mcp',
      version: pkg.version as string,
    })
  
    const client = CodeWikiClient.fromConfig(config)
  
    registerSearchReposTool(mcp, client)
    registerFetchRepoTool(mcp, client, config)
    registerAskRepoTool(mcp, client, config)
  
    return mcp
  }

• src/lib/codewikiClient.ts:188-214 (helper)

  The askRepository method in CodeWikiClient that makes the actual RPC call to codewiki.google to ask questions about a repository. Handles conversation history, normalizes repository input, and formats the response with metadata.

  async askRepository(repoInput: string, question: string, history: AskHistoryItem[] = []): Promise<WithMeta<string>> {
    const start = performance.now()
    const repo = normalizeRepoInput(repoInput)
  
    const messages: [string, 'user' | 'model'][] = [
      ...history.map(item => [item.content, item.role === 'assistant' ? 'model' : 'user'] as [string, 'user' | 'model']),
      [question, 'user'],
    ]
  
    const { payload, bytes } = await this.callRpc('EgIxfe', [messages, [null, repo.repoUrl]], {
      sourcePath: repo.sourcePath,
    })
  
    let data: string
    if (Array.isArray(payload) && typeof payload[0] === 'string') {
      data = payload[0]
    } else if (typeof payload === 'string') {
      data = payload
    } else {
      data = JSON.stringify(payload, null, 2)
    }
  
    return {
      data,
      meta: { totalBytes: bytes, totalElapsedMs: Math.round(performance.now() - start) },
    }
  }

• src/lib/repo.ts:52-73 (helper)

  The resolveRepoInput function that resolves various repository input formats (URL, owner/repo, or natural language) into a normalized repository object. Handles URL parsing, validation, and GitHub search for natural language queries.

  export async function resolveRepoInput(
    input: string,
    config?: Pick<CodeWikiConfig, 'githubToken' | 'requestTimeout'>,
  ): Promise<NormalizedRepo> {
    const raw = input.trim()
  
    // URL → sync
    if (/^https?:\/\//i.test(raw)) {
      return normalizeRepoInput(raw)
    }
  
    // owner/repo → sync
    const parts = raw.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean)
    if (parts.length === 2) {
      return normalizeRepoInput(raw)
    }
  
    // Natural language → NLP → GitHub search → normalize
    const keyword = extractKeyword(raw) ?? raw
    const fullName = await resolveRepoFromGitHub(keyword, config ?? { requestTimeout: 30_000 })
    return normalizeRepoInput(fullName)
  }