wip

Author: brendan-kellam

packages/mcp/src/client.ts

@@ -1,6 +1,6 @@
 import { env } from './env.js';
-import { listReposResponseSchema, searchResponseSchema, fileSourceResponseSchema, listCommitsResponseSchema } from './schemas.js';
-import { FileSourceRequest, ListReposQueryParams, SearchRequest, ListCommitsQueryParamsSchema } from './types.js';
+import { listReposResponseSchema, searchResponseSchema, fileSourceResponseSchema, listCommitsResponseSchema, askCodebaseResponseSchema } from './schemas.js';
+import { AskCodebaseRequest, AskCodebaseResponse, FileSourceRequest, ListReposQueryParams, SearchRequest, ListCommitsQueryParamsSchema } from './types.js';
 import { isServiceError, ServiceErrorException } from './utils.js';
 import { z } from 'zod';
 
@@ -103,3 +103,23 @@ export const listCommits = async (queryParams: ListCommitsQueryParamsSchema) =>
     const totalCount = parseInt(response.headers.get('X-Total-Count') ?? '0', 10);
     return { commits, totalCount };
 }
+
+/**
+ * Asks a natural language question about the codebase using the Sourcebot AI agent.
+ * This is a blocking call that runs the full agent loop and returns when complete.
+ * 
+ * @param request - The question and optional repo filters
+ * @returns The agent's answer, chat URL, sources, and metadata
+ */
+export const askCodebase = async (request: AskCodebaseRequest): Promise<AskCodebaseResponse> => {
+    const response = await fetch(`${env.SOURCEBOT_HOST}/api/chat/blocking`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})
+        },
+        body: JSON.stringify(request),
+    });
+
+    return parseResponse(response, askCodebaseResponseSchema);
+}

packages/mcp/src/index.ts

@@ -6,10 +6,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import _dedent from "dedent";
 import escapeStringRegexp from 'escape-string-regexp';
 import { z } from 'zod';
-import { getFileSource, listCommits, listRepos, search } from './client.js';
+import { askCodebase, getFileSource, listCommits, listRepos, search } from './client.js';
 import { env, numberSchema } from './env.js';
-import { fileSourceRequestSchema, listCommitsQueryParamsSchema, listReposQueryParamsSchema } from './schemas.js';
-import { FileSourceRequest, ListCommitsQueryParamsSchema, ListReposQueryParams, TextContent } from './types.js';
+import { askCodebaseRequestSchema, fileSourceRequestSchema, listCommitsQueryParamsSchema, listReposQueryParamsSchema } from './schemas.js';
+import { AskCodebaseRequest, FileSourceRequest, ListCommitsQueryParamsSchema, ListReposQueryParams, TextContent } from './types.js';
 
 const dedent = _dedent.withOptions({ alignValues: true });
 
@@ -239,7 +239,53 @@ server.tool(
     }
 );
 
+server.tool(
+    "ask_codebase",
+    dedent`
+    Ask a natural language question about the codebase. This tool uses an AI agent to autonomously search code, read files, and find symbol references/definitions to answer your question.
+
+    The agent will:
+    - Analyze your question and determine what context it needs
+    - Search the codebase using multiple strategies (code search, symbol lookup, file reading)
+    - Synthesize findings into a comprehensive answer with code references
+
+    Returns a detailed answer in markdown format with code references, plus a link to view the full research session (including all tool calls and reasoning) in the Sourcebot web UI.
+
+    This is a blocking operation that may take 30-60+ seconds for complex questions as the agent researches the codebase.
+    `,
+    {
+        question: z.string().describe("The question to ask about the codebase."),
+        repo: z.string().describe("The repository to ask the question on."),
+    },
+    async ({
+        question,
+        repo,
+    }) => {
+        const response = await askCodebase({
+            question,
+            repos: [repo],
+        });
 
+        // Format the response with the answer and a link to the chat
+        const formattedResponse = dedent`
+        ${response.answer}
+
+        ---
+        **View full research session:** ${response.chatUrl}
+
+        **Sources referenced:** ${response.sources.length} files
+        **Response time:** ${(response.metadata.totalResponseTimeMs / 1000).toFixed(1)}s
+        **Model:** ${response.metadata.modelName}
+        `;
+
+        return {
+            content: [{
+                type: "text",
+                text: formattedResponse,
+            }],
+        };
+    }
+);
 
 const runServer = async () => {
     const transport = new StdioServerTransport();

packages/mcp/src/schemas.ts

@@ -273,3 +273,35 @@ export const listCommitsResponseSchema = z.array(z.object({
     author_name: z.string(),
     author_email: z.string(),
 }));
+
+// ============================================================================
+// Ask Codebase (Blocking Chat API)
+// ============================================================================
+
+export const askCodebaseRequestSchema = z.object({
+    question: z.string().describe("The question to ask about the codebase"),
+    repos: z.array(z.string()).optional().describe("Optional: filter to specific repositories by name"),
+});
+
+export const sourceSchema = z.object({
+    type: z.literal('file'),
+    repo: z.string(),
+    path: z.string(),
+    name: z.string(),
+    language: z.string(),
+    revision: z.string(),
+});
+
+export const askCodebaseResponseSchema = z.object({
+    answer: z.string().describe("The agent's final answer in markdown format"),
+    chatId: z.string().describe("ID of the persisted chat session"),
+    chatUrl: z.string().describe("URL to view the chat in the web UI"),
+    sources: z.array(sourceSchema).describe("Files the agent referenced during research"),
+    metadata: z.object({
+        totalTokens: z.number(),
+        inputTokens: z.number(),
+        outputTokens: z.number(),
+        totalResponseTimeMs: z.number(),
+        modelName: z.string(),
+    }).describe("Metadata about the response"),
+});

packages/mcp/src/types.ts

@@ -12,6 +12,8 @@ import {
     serviceErrorSchema,
     listCommitsQueryParamsSchema,
     listCommitsResponseSchema,
+    askCodebaseRequestSchema,
+    askCodebaseResponseSchema,
 } from "./schemas.js";
 import { z } from "zod";
 
@@ -34,3 +36,6 @@ export type ServiceError = z.infer<typeof serviceErrorSchema>;
 
 export type ListCommitsQueryParamsSchema = z.infer<typeof listCommitsQueryParamsSchema>;
 export type ListCommitsResponse = z.infer<typeof listCommitsResponseSchema>;
+
+export type AskCodebaseRequest = z.infer<typeof askCodebaseRequestSchema>;
+export type AskCodebaseResponse = z.infer<typeof askCodebaseResponseSchema>;