@sourcebot/mcp 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.14] - 2026-01-27
+
+### Changed
+- Updated README.
+
+## [1.0.13] - 2026-01-27
+
+### Added
+- Added `search_commits` tool to search a repos commit history. [#625](https://github.com/sourcebot-dev/sourcebot/pull/625)
+- Added `gitRevision` parameter to the `search_code` tool to allow for searching on different branches. [#625](https://github.com/sourcebot-dev/sourcebot/pull/625)
+- Added server side pagination support for `list_commits` and `list_repos`. [#795](https://github.com/sourcebot-dev/sourcebot/pull/795)
+- Added `filterByFilepaths` and `useRegex` params to the `search_code` tool. [#795](https://github.com/sourcebot-dev/sourcebot/pull/795)
+
+### Changed
+- Renamed `search_commits` tool to `list_commits`. [#795](https://github.com/sourcebot-dev/sourcebot/pull/795)
+- Renamed `gitRevision` param to `ref` on `search_code` tool. [#795](https://github.com/sourcebot-dev/sourcebot/pull/795)
+- Generally improved tool and tool param descriptions for all tools. [#795](https://github.com/sourcebot-dev/sourcebot/pull/795)
+
 ## [1.0.12] - 2026-01-13
 
 ### Fixed

package/README.md

@@ -164,19 +164,22 @@ For a more detailed guide, checkout [the docs](https://docs.sourcebot.dev/docs/f
 
 ### search_code
 
-Fetches code that matches the provided regex pattern in `query`.
+Searches for code that matches the provided search query as a substring by default, or as a regular expression if `useRegex` is true.
 
 <details>
 <summary>Parameters</summary>
 
 | Name                  | Required | Description                                                                                                                       |
 |:----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------|
-| `query`               | yes      | Regex pattern to search for. Escape special characters and spaces with a single backslash (e.g., 'console\.log', 'console\ log'). |
-| `filterByRepoIds`     | no       | Restrict search to specific repository IDs (from 'list_repos'). Leave empty to search all.                                        |
-| `filterByLanguages`   | no       | Restrict search to specific languages (GitHub linguist format, e.g., Python, JavaScript).                                         |
-| `caseSensitive`       | no       | Case sensitive search (default: false).                                                                                           |
-| `includeCodeSnippets` | no       | Include code snippets in results (default: false).                                                                                |
-| `maxTokens`           | no       | Max tokens to return (default: env.DEFAULT_MINIMUM_TOKENS).                                                                       |
+| `query`               | yes      | The search pattern to match against code contents. Do not escape quotes in your query.                                            |
+| `useRegex`            | no       | Whether to use regular expression matching. When false, substring matching is used (default: false).                              |
+| `filterByRepos`       | no       | Scope the search to specific repositories.                                                                                        |
+| `filterByLanguages`   | no       | Scope the search to specific languages.                                                                                           |
+| `filterByFilepaths`   | no       | Scope the search to specific filepaths.                                                                                           |
+| `caseSensitive`       | no       | Whether the search should be case sensitive (default: false).                                                                     |
+| `includeCodeSnippets` | no       | Whether to include code snippets in the response (default: false).                                                                |
+| `ref`                 | no       | Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch.                                     |
+| `maxTokens`           | no       | The maximum number of tokens to return (default: 10000). Higher values provide more context but consume more tokens.              |
 </details>
 
 
@@ -187,25 +190,48 @@ Lists repositories indexed by Sourcebot with optional filtering and pagination.
 <details>
 <summary>Parameters</summary>
 
-| Name         | Required | Description                                                         |
-|:-------------|:---------|:--------------------------------------------------------------------|
-| `query`      | no       | Filter repositories by name (case-insensitive).                     |
-| `pageNumber` | no       | Page number (1-indexed, default: 1).                                |
-| `limit`      | no       | Number of repositories per page (default: 50).                      |
+| Name        | Required | Description                                                                     |
+|:------------|:---------|:--------------------------------------------------------------------------------|
+| `query`     | no       | Filter repositories by name (case-insensitive).                                 |
+| `page`      | no       | Page number for pagination (min 1, default: 1).                                 |
+| `perPage`   | no       | Results per page for pagination (min 1, max 100, default: 30).                  |
+| `sort`      | no       | Sort repositories by 'name' or 'pushed' (most recent commit). Default: 'name'. |
+| `direction` | no       | Sort direction: 'asc' or 'desc' (default: 'asc').                               |
 
 </details>
 
-### get_file_source
+### read_file
 
-Fetches the source code for a given file.
+Reads the source code for a given file.
 
 <details>
 <summary>Parameters</summary>
 
-| Name         | Required | Description                                                      |
-|:-------------|:---------|:-----------------------------------------------------------------|
-| `fileName`   | yes      | The file to fetch the source code for.                           |
-| `repoId`     | yes      | The Sourcebot repository ID.                                     |
+| Name   | Required | Description                                                                                                    |
+|:-------|:---------|:---------------------------------------------------------------------------------------------------------------|
+| `repo` | yes      | The repository name.                                                                                           |
+| `path` | yes      | The path to the file.                                                                                          |
+| `ref`  | no       | Commit SHA, branch or tag name to fetch the source code for. If not provided, uses the default branch.         |
+</details>
+
+### list_commits
+
+Get a list of commits for a given repository.
+
+<details>
+<summary>Parameters</summary>
+
+| Name      | Required | Description                                                                                                                           |
+|:----------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------|
+| `repo`    | yes      | The name of the repository to list commits for.                                                                                       |
+| `query`   | no       | Search query to filter commits by message content (case-insensitive).                                                                 |
+| `since`   | no       | Show commits more recent than this date. Supports ISO 8601 (e.g., '2024-01-01') or relative formats (e.g., '30 days ago').            |
+| `until`   | no       | Show commits older than this date. Supports ISO 8601 (e.g., '2024-12-31') or relative formats (e.g., 'yesterday').                    |
+| `author`  | no       | Filter commits by author name or email (case-insensitive).                                                                            |
+| `ref`     | no       | Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch.                                          |
+| `page`    | no       | Page number for pagination (min 1, default: 1).                                                                                       |
+| `perPage` | no       | Results per page for pagination (min 1, max 100, default: 50).                                                                        |
+
 </details>
 
 

package/dist/client.d.ts

@@ -1,4 +1,124 @@
-import { FileSourceRequest, FileSourceResponse, ListRepositoriesResponse, SearchRequest, SearchResponse, ServiceError } from './types.js';
-export declare const search: (request: SearchRequest) => Promise<SearchResponse | ServiceError>;
-export declare const listRepos: () => Promise<ListRepositoriesResponse | ServiceError>;
-export declare const getFileSource: (request: FileSourceRequest) => Promise<FileSourceResponse | ServiceError>;
+import { FileSourceRequest, ListReposQueryParams, SearchRequest, ListCommitsQueryParamsSchema } from './types.js';
+export declare const search: (request: SearchRequest) => Promise<{
+    stats: {
+        actualMatchCount: number;
+        totalMatchCount: number;
+        duration: number;
+        fileCount: number;
+        filesSkipped: number;
+        contentBytesLoaded: number;
+        indexBytesLoaded: number;
+        crashes: number;
+        shardFilesConsidered: number;
+        filesConsidered: number;
+        filesLoaded: number;
+        shardsScanned: number;
+        shardsSkipped: number;
+        shardsSkippedFilter: number;
+        ngramMatches: number;
+        ngramLookups: number;
+        wait: number;
+        matchTreeConstruction: number;
+        matchTreeSearch: number;
+        regexpsConsidered: number;
+        flushReason: string;
+    };
+    files: {
+        webUrl: string;
+        fileName: {
+            text: string;
+            matchRanges: {
+                start: {
+                    byteOffset: number;
+                    lineNumber: number;
+                    column: number;
+                };
+                end: {
+                    byteOffset: number;
+                    lineNumber: number;
+                    column: number;
+                };
+            }[];
+        };
+        repository: string;
+        repositoryId: number;
+        language: string;
+        chunks: {
+            matchRanges: {
+                start: {
+                    byteOffset: number;
+                    lineNumber: number;
+                    column: number;
+                };
+                end: {
+                    byteOffset: number;
+                    lineNumber: number;
+                    column: number;
+                };
+            }[];
+            content: string;
+            contentStart: {
+                byteOffset: number;
+                lineNumber: number;
+                column: number;
+            };
+            symbols?: {
+                symbol: string;
+                kind: string;
+                parent?: {
+                    symbol: string;
+                    kind: string;
+                } | undefined;
+            }[] | undefined;
+        }[];
+        externalWebUrl?: string | undefined;
+        content?: string | undefined;
+        branches?: string[] | undefined;
+    }[];
+    repositoryInfo: {
+        id: number;
+        codeHostType: string;
+        name: string;
+        displayName?: string | undefined;
+        webUrl?: string | undefined;
+    }[];
+    isSearchExhaustive: boolean;
+}>;
+export declare const listRepos: (queryParams?: ListReposQueryParams) => Promise<{
+    repos: {
+        codeHostType: string;
+        webUrl: string;
+        repoId: number;
+        repoName: string;
+        externalWebUrl?: string | undefined;
+        repoDisplayName?: string | undefined;
+        imageUrl?: string | undefined;
+        indexedAt?: Date | undefined;
+        pushedAt?: Date | undefined;
+    }[];
+    totalCount: number;
+}>;
+export declare const getFileSource: (request: FileSourceRequest) => Promise<{
+    path: string;
+    source: string;
+    webUrl: string;
+    language: string;
+    repo: string;
+    repoCodeHostType: string;
+    externalWebUrl?: string | undefined;
+    repoDisplayName?: string | undefined;
+    repoExternalWebUrl?: string | undefined;
+    branch?: string | undefined;
+}>;
+export declare const listCommits: (queryParams: ListCommitsQueryParamsSchema) => Promise<{
+    commits: {
+        message: string;
+        date: string;
+        hash: string;
+        refs: string;
+        body: string;
+        author_name: string;
+        author_email: string;
+    }[];
+    totalCount: number;
+}>;

package/dist/client.js

@@ -1,45 +1,85 @@
 import { env } from './env.js';
-import { listRepositoriesResponseSchema, searchResponseSchema, fileSourceResponseSchema } from './schemas.js';
-import { isServiceError } from './utils.js';
+import { listReposResponseSchema, searchResponseSchema, fileSourceResponseSchema, listCommitsResponseSchema } from './schemas.js';
+import { isServiceError, ServiceErrorException } from './utils.js';
+const parseResponse = async (response, schema) => {
+    const text = await response.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid JSON response: ${text}`);
+    }
+    // Check if the response is already a service error from the API
+    if (isServiceError(json)) {
+        throw new ServiceErrorException(json);
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error(`Failed to parse response: ${parsed.error.message}`);
+    }
+    return parsed.data;
+};
 export const search = async (request) => {
-    const result = await fetch(`${env.SOURCEBOT_HOST}/api/search`, {
+    const response = await fetch(`${env.SOURCEBOT_HOST}/api/search`, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
             ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})
         },
         body: JSON.stringify(request)
-    }).then(response => response.json());
-    if (isServiceError(result)) {
-        return result;
-    }
-    return searchResponseSchema.parse(result);
+    });
+    return parseResponse(response, searchResponseSchema);
 };
-export const listRepos = async () => {
-    const result = await fetch(`${env.SOURCEBOT_HOST}/api/repos`, {
+export const listRepos = async (queryParams = {}) => {
+    const url = new URL(`${env.SOURCEBOT_HOST}/api/repos`);
+    for (const [key, value] of Object.entries(queryParams)) {
+        if (value) {
+            url.searchParams.set(key, value.toString());
+        }
+    }
+    const response = await fetch(url, {
         method: 'GET',
         headers: {
             'Content-Type': 'application/json',
             ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})
         },
-    }).then(response => response.json());
-    if (isServiceError(result)) {
-        return result;
-    }
-    return listRepositoriesResponseSchema.parse(result);
+    });
+    const repos = await parseResponse(response, listReposResponseSchema);
+    const totalCount = parseInt(response.headers.get('X-Total-Count') ?? '0', 10);
+    return { repos, totalCount };
 };
 export const getFileSource = async (request) => {
-    const result = await fetch(`${env.SOURCEBOT_HOST}/api/source`, {
-        method: 'POST',
+    const url = new URL(`${env.SOURCEBOT_HOST}/api/source`);
+    for (const [key, value] of Object.entries(request)) {
+        if (value) {
+            url.searchParams.set(key, value.toString());
+        }
+    }
+    const response = await fetch(url, {
+        method: 'GET',
         headers: {
-            'Content-Type': 'application/json',
             ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})
         },
-        body: JSON.stringify(request)
-    }).then(response => response.json());
-    if (isServiceError(result)) {
-        return result;
+    });
+    return parseResponse(response, fileSourceResponseSchema);
+};
+export const listCommits = async (queryParams) => {
+    const url = new URL(`${env.SOURCEBOT_HOST}/api/commits`);
+    for (const [key, value] of Object.entries(queryParams)) {
+        if (value) {
+            url.searchParams.set(key, value.toString());
+        }
     }
-    return fileSourceResponseSchema.parse(result);
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+            'X-Org-Domain': '~',
+            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})
+        },
+    });
+    const commits = await parseResponse(response, listCommitsResponseSchema);
+    const totalCount = parseInt(response.headers.get('X-Total-Count') ?? '0', 10);
+    return { commits, totalCount };
 };
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE9G,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,EAAE,OAAsB,EAA0C,EAAE;IAC3F,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,cAAc,aAAa,EAAE;QAC3D,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACL,cAAc,EAAE,kBAAkB;YAClC,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAChC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAErC,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,OAAO,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,IAAsD,EAAE;IAClF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,cAAc,YAAY,EAAE;QAC1D,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACL,cAAc,EAAE,kBAAkB;YAClC,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF;KACJ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAErC,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,OAAO,8BAA8B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,OAA0B,EAA8C,EAAE;IAC1G,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,cAAc,aAAa,EAAE;QAC3D,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACL,cAAc,EAAE,kBAAkB;YAClC,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAChC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAErC,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAClB,CAAC;IAED,OAAO,wBAAwB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAClD,CAAC,CAAA","sourcesContent":["import { env } from './env.js';\nimport { listRepositoriesResponseSchema, searchResponseSchema, fileSourceResponseSchema } from './schemas.js';\nimport { FileSourceRequest, FileSourceResponse, ListRepositoriesResponse, SearchRequest, SearchResponse, ServiceError } from './types.js';\nimport { isServiceError } from './utils.js';\n\nexport const search = async (request: SearchRequest): Promise<SearchResponse | ServiceError> => {\n    const result = await fetch(`${env.SOURCEBOT_HOST}/api/search`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n        body: JSON.stringify(request)\n    }).then(response => response.json());\n\n    if (isServiceError(result)) {\n        return result;\n    }\n\n    return searchResponseSchema.parse(result);\n}\n\nexport const listRepos = async (): Promise<ListRepositoriesResponse | ServiceError> => {\n    const result = await fetch(`${env.SOURCEBOT_HOST}/api/repos`, {\n        method: 'GET',\n        headers: {\n            'Content-Type': 'application/json',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n    }).then(response => response.json());\n\n    if (isServiceError(result)) {\n        return result;\n    }\n\n    return listRepositoriesResponseSchema.parse(result);\n}\n\nexport const getFileSource = async (request: FileSourceRequest): Promise<FileSourceResponse | ServiceError> => {\n    const result = await fetch(`${env.SOURCEBOT_HOST}/api/source`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n        body: JSON.stringify(request)\n    }).then(response => response.json());\n\n    if (isServiceError(result)) {\n        return result;\n    }\n\n    return fileSourceResponseSchema.parse(result);\n}\n"]}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { env } from './env.js';\nimport { listReposResponseSchema, searchResponseSchema, fileSourceResponseSchema, listCommitsResponseSchema } from './schemas.js';\nimport { FileSourceRequest, ListReposQueryParams, SearchRequest, ListCommitsQueryParamsSchema } from './types.js';\nimport { isServiceError, ServiceErrorException } from './utils.js';\nimport { z } from 'zod';\n\nconst parseResponse = async <T extends z.ZodTypeAny>(\n    response: Response,\n    schema: T\n): Promise<z.infer<T>> => {\n    const text = await response.text();\n\n    let json: unknown;\n    try {\n        json = JSON.parse(text);\n    } catch {\n        throw new Error(`Invalid JSON response: ${text}`);\n    }\n\n    // Check if the response is already a service error from the API\n    if (isServiceError(json)) {\n        throw new ServiceErrorException(json);\n    }\n\n    const parsed = schema.safeParse(json);\n    if (!parsed.success) {\n        throw new Error(`Failed to parse response: ${parsed.error.message}`);\n    }\n\n    return parsed.data;\n};\n\nexport const search = async (request: SearchRequest) => {\n    const response = await fetch(`${env.SOURCEBOT_HOST}/api/search`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n        body: JSON.stringify(request)\n    });\n\n    return parseResponse(response, searchResponseSchema);\n}\n\nexport const listRepos = async (queryParams: ListReposQueryParams = {}) => {\n    const url = new URL(`${env.SOURCEBOT_HOST}/api/repos`);\n\n    for (const [key, value] of Object.entries(queryParams)) {\n        if (value) {\n            url.searchParams.set(key, value.toString());\n        }\n    }\n\n    const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n            'Content-Type': 'application/json',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n    });\n\n    const repos = await parseResponse(response, listReposResponseSchema);\n    const totalCount = parseInt(response.headers.get('X-Total-Count') ?? '0', 10);\n    return { repos, totalCount };\n}\n\nexport const getFileSource = async (request: FileSourceRequest) => {\n    const url = new URL(`${env.SOURCEBOT_HOST}/api/source`);\n    for (const [key, value] of Object.entries(request)) {\n        if (value) {\n            url.searchParams.set(key, value.toString());\n        }\n    }\n\n    const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n    });\n\n    return parseResponse(response, fileSourceResponseSchema);\n}\n\nexport const listCommits = async (queryParams: ListCommitsQueryParamsSchema) => {\n    const url = new URL(`${env.SOURCEBOT_HOST}/api/commits`);\n    for (const [key, value] of Object.entries(queryParams)) {\n        if (value) {\n            url.searchParams.set(key, value.toString());\n        }\n    }\n\n    const response = await fetch(url, {\n        method: 'GET',\n        headers: {\n            'X-Org-Domain': '~',\n            ...(env.SOURCEBOT_API_KEY ? { 'X-Sourcebot-Api-Key': env.SOURCEBOT_API_KEY } : {})\n        },\n    });\n\n    const commits = await parseResponse(response, listCommitsResponseSchema);\n    const totalCount = parseInt(response.headers.get('X-Total-Count') ?? '0', 10);\n    return { commits, totalCount };\n}\n"]}

package/dist/index.js

@@ -2,36 +2,45 @@
 // Entry point for the MCP server
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import _dedent from "dedent";
 import escapeStringRegexp from 'escape-string-regexp';
 import { z } from 'zod';
-import { listRepos, search, getFileSource } from './client.js';
+import { getFileSource, listCommits, listRepos, search } from './client.js';
 import { env, numberSchema } from './env.js';
-import { listReposRequestSchema } from './schemas.js';
-import { isServiceError } from './utils.js';
+import { fileSourceRequestSchema, listCommitsQueryParamsSchema, listReposQueryParamsSchema } from './schemas.js';
+const dedent = _dedent.withOptions({ alignValues: true });
 // Create MCP server
 const server = new McpServer({
     name: 'sourcebot-mcp-server',
     version: '0.1.0',
 });
-server.tool("search_code", `Fetches code that matches the provided regex pattern in \`query\`. This is NOT a semantic search.
-    Results are returned as an array of matching files, with the file's URL, repository, and language.
-    If you receive an error that indicates that you're not authenticated, please inform the user to set the SOURCEBOT_API_KEY environment variable.
-    If the \`includeCodeSnippets\` property is true, code snippets containing the matches will be included in the response. Only set this to true if the request requires code snippets (e.g., show me examples where library X is used).
-    When referencing a file in your response, **ALWAYS** include the file's external URL as a link. This makes it easier for the user to view the file, even if they don't have it locally checked out.
-    **ONLY USE** the \`filterByRepoIds\` property if the request requires searching a specific repo(s). Otherwise, leave it empty.`, {
+server.tool("search_code", dedent `
+    Searches for code that matches the provided search query as a substring by default, or as a regular expression if useRegex is true. Useful for exploring remote repositories by searching for exact symbols, functions, variables, or specific code patterns. To determine if a repository is indexed, use the \`list_repos\` tool. By default, searches are global and will search the default branch of all repositories. Searches can be scoped to specific repositories, languages, and branches. When referencing code outputted by this tool, always include the file's external URL as a link. This makes it easier for the user to view the file, even if they don't have it locally checked out.
+    `, {
     query: z
         .string()
-        .describe(`The regex pattern to search for. RULES:
-        1. When a regex special character needs to be escaped, ALWAYS use a single backslash (\) (e.g., 'console\.log')
-        2. **ALWAYS** escape spaces with a single backslash (\) (e.g., 'console\ log')
-        `),
-    filterByRepoIds: z
+        .describe(`The search pattern to match against code contents. Do not escape quotes in your query.`)
+        // Escape backslashes first, then quotes, and wrap in double quotes
+        // so the query is treated as a literal phrase (like grep).
+        .transform((val) => {
+        const escaped = val.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `"${escaped}"`;
+    }),
+    useRegex: z
+        .boolean()
+        .describe(`Whether to use regular expression matching to match the search query against code contents. When false, substring matching is used. (default: false)`)
+        .optional(),
+    filterByRepos: z
         .array(z.string())
-        .describe(`Scope the search to the provided repositories to the Sourcebot compatible repository IDs. **DO NOT** use this property if you want to search all repositories. **YOU MUST** call 'list_repos' first to obtain the exact repository ID.`)
+        .describe(`Scope the search to the provided repositories.`)
         .optional(),
     filterByLanguages: z
         .array(z.string())
-        .describe(`Scope the search to the provided languages. The language MUST be formatted as a GitHub linguist language. Examples: Python, JavaScript, TypeScript, Java, C#, C++, PHP, Go, Rust, Ruby, Swift, Kotlin, Shell, C, Dart, HTML, CSS, PowerShell, SQL, R`)
+        .describe(`Scope the search to the provided languages.`)
+        .optional(),
+    filterByFilepaths: z
+        .array(z.string())
+        .describe(`Scope the search to the provided filepaths.`)
         .optional(),
     caseSensitive: z
         .boolean()
@@ -39,35 +48,37 @@ server.tool("search_code", `Fetches code that matches the provided regex pattern
         .optional(),
     includeCodeSnippets: z
         .boolean()
-        .describe(`Whether to include the code snippets in the response (default: false). If false, only the file's URL, repository, and language will be returned. Set to false to get a more concise response.`)
+        .describe(`Whether to include the code snippets in the response. If false, only the file's URL, repository, and language will be returned. (default: false)`)
+        .optional(),
+    ref: z
+        .string()
+        .describe(`Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch (usually 'main' or 'master').`)
         .optional(),
     maxTokens: numberSchema
         .describe(`The maximum number of tokens to return (default: ${env.DEFAULT_MINIMUM_TOKENS}). Higher values provide more context but consume more tokens. Values less than ${env.DEFAULT_MINIMUM_TOKENS} will be ignored.`)
         .transform((val) => (val < env.DEFAULT_MINIMUM_TOKENS ? env.DEFAULT_MINIMUM_TOKENS : val))
         .optional(),
-}, async ({ query, filterByRepoIds: repoIds = [], filterByLanguages: languages = [], maxTokens = env.DEFAULT_MINIMUM_TOKENS, includeCodeSnippets = false, caseSensitive = false, }) => {
-    if (repoIds.length > 0) {
-        query += ` ( repo:${repoIds.map(id => escapeStringRegexp(id)).join(' or repo:')} )`;
+}, async ({ query, filterByRepos: repos = [], filterByLanguages: languages = [], filterByFilepaths: filepaths = [], maxTokens = env.DEFAULT_MINIMUM_TOKENS, includeCodeSnippets = false, caseSensitive = false, ref, useRegex = false, }) => {
+    if (repos.length > 0) {
+        query += ` (repo:${repos.map(id => escapeStringRegexp(id)).join(' or repo:')})`;
     }
     if (languages.length > 0) {
-        query += ` ( lang:${languages.join(' or lang:')} )`;
+        query += ` (lang:${languages.join(' or lang:')})`;
+    }
+    if (filepaths.length > 0) {
+        query += ` (file:${filepaths.map(filepath => escapeStringRegexp(filepath)).join(' or file:')})`;
+    }
+    if (ref) {
+        query += ` ( rev:${ref} )`;
     }
     const response = await search({
         query,
         matches: env.DEFAULT_MATCHES,
         contextLines: env.DEFAULT_CONTEXT_LINES,
-        isRegexEnabled: true,
+        isRegexEnabled: useRegex,
         isCaseSensitivityEnabled: caseSensitive,
-        source: 'mcp'
+        source: 'mcp',
     });
-    if (isServiceError(response)) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Error searching code: ${response.message}`,
-                }],
-        };
-    }
     if (response.files.length === 0) {
         return {
             content: [{
@@ -81,8 +92,12 @@ server.tool("search_code", `Fetches code that matches the provided regex pattern
     let isResponseTruncated = false;
     for (const file of response.files) {
         const numMatches = file.chunks.reduce((acc, chunk) => acc + chunk.matchRanges.length, 0);
-        const fileIdentifier = file.webUrl ?? file.fileName.text;
-        let text = `file: ${fileIdentifier}\nnum_matches: ${numMatches}\nrepository: ${file.repository}\nlanguage: ${file.language}`;
+        let text = dedent `
+            file: ${file.webUrl}
+            num_matches: ${numMatches}
+            repo: ${file.repository}
+            language: ${file.language}
+            `;
         if (includeCodeSnippets) {
             const snippets = file.chunks.map(chunk => {
                 return `\`\`\`\n${chunk.content}\n\`\`\``;
@@ -124,76 +139,40 @@ server.tool("search_code", `Fetches code that matches the provided regex pattern
         content,
     };
 });
-server.tool("list_repos", "Lists repositories in the organization with optional filtering and pagination. If you receive an error that indicates that you're not authenticated, please inform the user to set the SOURCEBOT_API_KEY environment variable.", listReposRequestSchema.shape, async ({ query, pageNumber = 1, limit = 50 }) => {
-    const response = await listRepos();
-    if (isServiceError(response)) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Error listing repositories: ${response.message}`,
-                }],
-        };
-    }
-    // Apply query filter if provided
-    let filtered = response;
-    if (query) {
-        const lowerQuery = query.toLowerCase();
-        filtered = response.filter(repo => repo.repoName.toLowerCase().includes(lowerQuery) ||
-            repo.repoDisplayName?.toLowerCase().includes(lowerQuery));
-    }
-    // Sort alphabetically for consistent pagination
-    filtered.sort((a, b) => a.repoName.localeCompare(b.repoName));
-    // Apply pagination
-    const startIndex = (pageNumber - 1) * limit;
-    const endIndex = startIndex + limit;
-    const paginated = filtered.slice(startIndex, endIndex);
-    // Format output
-    const content = paginated.map(repo => {
-        const repoUrl = repo.webUrl ?? repo.repoCloneUrl;
-        return {
-            type: "text",
-            text: `id: ${repo.repoName}\nurl: ${repoUrl}`,
-        };
-    });
-    // Add pagination info
-    if (content.length === 0 && filtered.length > 0) {
-        content.push({
-            type: "text",
-            text: `No results on page ${pageNumber}. Total matching repositories: ${filtered.length}`,
-        });
-    }
-    else if (filtered.length > endIndex) {
-        content.push({
-            type: "text",
-            text: `Showing ${paginated.length} repositories (page ${pageNumber}). Total matching: ${filtered.length}. Use pageNumber ${pageNumber + 1} to see more.`,
-        });
-    }
+server.tool("list_commits", dedent `Get a list of commits for a given repository.`, listCommitsQueryParamsSchema.shape, async (request) => {
+    const result = await listCommits(request);
     return {
-        content,
+        content: [{
+                type: "text", text: JSON.stringify(result)
+            }],
     };
 });
-server.tool("get_file_source", "Fetches the source code for a given file. If you receive an error that indicates that you're not authenticated, please inform the user to set the SOURCEBOT_API_KEY environment variable.", {
-    fileName: z.string().describe("The file to fetch the source code for."),
-    repoId: z.string().describe("The repository to fetch the source code for. This is the Sourcebot compatible repository ID."),
-}, async ({ fileName, repoId }) => {
-    const response = await getFileSource({
-        fileName,
-        repository: repoId,
-    });
-    if (isServiceError(response)) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Error fetching file source: ${response.message}`,
-                }],
-        };
-    }
-    const content = [{
-            type: "text",
-            text: `file: ${fileName}\nrepository: ${repoId}\nlanguage: ${response.language}\nsource:\n${response.source}`,
-        }];
+server.tool("list_repos", dedent `Lists repositories in the organization with optional filtering and pagination.`, listReposQueryParamsSchema.shape, async (request) => {
+    const result = await listRepos(request);
     return {
-        content,
+        content: [{
+                type: "text", text: JSON.stringify({
+                    repos: result.repos.map((repo) => ({
+                        name: repo.repoName,
+                        url: repo.webUrl,
+                        pushedAt: repo.pushedAt,
+                    })),
+                    totalCount: result.totalCount,
+                })
+            }]
+    };
+});
+server.tool("read_file", dedent `Reads the source code for a given file.`, fileSourceRequestSchema.shape, async (request) => {
+    const response = await getFileSource(request);
+    return {
+        content: [{
+                type: "text", text: JSON.stringify({
+                    source: response.source,
+                    language: response.language,
+                    path: response.path,
+                    url: response.webUrl,
+                })
+            }]
     };
 });
 const runServer = async () => {