Skip to content

Commit 453c506

Browse files
brendan-kellambrendan-kellam
committed
updated docs
1 parent 02709a9 commit 453c506

File tree

4 files changed

+255
-41
lines changed

4 files changed

+255
-41
lines changed

‎docs/docs/more/mcp-server.mdx

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
1313

1414
<Steps>
1515
<Step title="Launch Sourcebot">
16-
Follow the self-hosting [quick start guide](/self-hosting/overview#quick-start-guide) to launch Sourcebot and get your code indexed.
16+
Follow the self-hosting [quick start guide](/self-hosting/overview#quick-start-guide) to launch Sourcebot and get your code indexed. The host url of your instance (e.g., `http://localhost:3000`) is passed to the MCP server via the `SOURCEBOT_HOST` url.
17+
18+
If a host is not provided, then the server will fallback to using the demo instance hosted at https://demo.sourcebot.dev. You can see the list of repositories indexed [here](https://demo.sourcebot.dev/~/repos). Add additional repositories by [opening a PR](https://github.com/sourcebot-dev/sourcebot/blob/main/demo-site-config.json).
1719
</Step>
1820

1921
<Step title="Install the MCP server">
@@ -83,6 +85,9 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
8385
"type": "stdio",
8486
"command": "npx",
8587
"args": ["-y", "@sourcebot/mcp@latest"]
88+
},
89+
"env": {
90+
"SOURCEBOT_HOST": "http://localhost:3000"
8691
}
8792
}
8893
}
@@ -97,7 +102,7 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
97102
Run the following command:
98103

99104
```sh
100-
claude mcp add sourcebot -e http://localhost:3000 -- npx -y @sourcebot/mcp@latest
105+
claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -- npx -y @sourcebot/mcp@latest
101106
```
102107

103108
Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
@@ -126,6 +131,10 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)
126131
</AccordionGroup>
127132
</Step>
128133

134+
<Step title="Prompt the LLM">
135+
Tell your LLM to `use sourcebot` when prompting.
136+
</Step>
137+
129138
</Steps>
130139

131140

‎packages/mcp/README.md

Lines changed: 201 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,197 @@
1-
# Sourcebot MCP - search code on GitHub, GitLab, BitBucket, and more
1+
# Sourcebot MCP - Blazingly fast agentic code search for GitHub, GitLab, BitBucket, and more
22

33
[![Sourcebot](https://img.shields.io/badge/Website-sourcebot.dev-blue)](https://sourcebot.dev)
44
[![GitHub](https://img.shields.io/badge/GitHub-sourcebot--dev%2Fsourcebot-green?logo=github)](https://github.com/sourcebot-dev/sourcebot)
55
[![Docs](https://img.shields.io/badge/Docs-docs.sourcebot.dev-yellow)](https://docs.sourcebot.dev/docs/more/mcp-server)
66
[![npm](https://img.shields.io/npm/v/@sourcebot/mcp)](https://www.npmjs.com/package/@sourcebot/mcp)
77

88

9-
An MCP server that provides blazingly fast regex-based code search, allowing LLMs to fetch code context from repositories you don't have checked out.
9+
The Sourcebot MCP server enables precise regular expression code search across repos hosted on [GitHub](https://docs.sourcebot.dev/docs/connections/github), [GitLab](https://docs.sourcebot.dev/docs/connections/gitlab), [BitBucket](https://docs.sourcebot.dev/docs/connections/bitbucket-cloud) and [more](#supported-code-hosts). This unlocks the capability for LLM agents to fetch code context for repositories that aren't checked out locally. Some use cases where precise search on a wider code context can help:
10+
11+
- Enriching responses to user requests:
12+
- _"What repositories are using internal library X?"_
13+
- _"Provide usage examples of the CodeMirror component"_
14+
- _"Where is the `useCodeMirrorTheme` hook defined?"_
15+
- _"Find all usages of `deprecatedApi` across all repos"_
16+
17+
- Improving reasoning ability for existing horizontal agents like AI code review, docs generation, etc.
18+
- _"Find the definitions for all functions in this diff"_
19+
- _"Document what systems depend on this class"_
20+
21+
- Building custom LLM horizontal agents like like compliance auditing agents, migration agents, etc.
22+
- _"Find all instances of hardcoded credentials"_
23+
- _"Identify repositories that depend on this depreacted api"_
24+
1025

1126
## Getting Started
12-
Please follow [these docs](https://docs.sourcebot.dev/docs/more/mcp-server) to get started.
27+
28+
1. Install Node.JS >= v18.0.0.
29+
30+
2. (optional) Spin up a Sourcebot instance by following [this guide](https://docs.sourcebot.dev/self-hosting/overview). The host url of your instance (e.g., `http://localhost:3000`) is passed to the MCP server via the `SOURCEBOT_HOST` url.
31+
32+
If a host is not provided, then the server will fallback to using the demo instance hosted at https://demo.sourcebot.dev. You can see the list of repositories indexed [here](https://demo.sourcebot.dev/~/repos). Add additional repositories by [opening a PR](https://github.com/sourcebot-dev/sourcebot/blob/main/demo-site-config.json).
33+
34+
3. Install `@sourcebot/mcp` into your MCP client:
35+
36+
<details>
37+
<summary>Cursor</summary>
38+
39+
[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol)
40+
41+
Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
42+
43+
Paste the following into your `~/.cursor/mcp.json` file. This will install Sourcebot globally within Cursor:
44+
45+
```json
46+
{
47+
"mcpServers": {
48+
"sourcebot": {
49+
"command": "npx",
50+
"args": ["-y", "@sourcebot/mcp@latest" ],
51+
// Optional - if not specified, https://demo.sourcebot.dev is used
52+
"env": {
53+
"SOURCEBOT_HOST": "http://localhost:3000"
54+
}
55+
}
56+
}
57+
}
58+
```
59+
</details>
60+
61+
<details>
62+
<summary>Windsurf</summary>
63+
64+
[Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp)
65+
66+
Go to: `Windsurf Settings` -> `Cascade` -> `Add Server` -> `Add Custom Server`
67+
68+
Paste the following into your `mcp_config.json` file:
69+
70+
```json
71+
{
72+
"mcpServers": {
73+
"sourcebot": {
74+
"command": "npx",
75+
"args": ["-y", "@sourcebot/mcp@latest" ],
76+
// Optional - if not specified, https://demo.sourcebot.dev is used
77+
"env": {
78+
"SOURCEBOT_HOST": "http://localhost:3000"
79+
}
80+
}
81+
}
82+
}
83+
```
84+
</details>
85+
86+
<details>
87+
<summary>VS Code</summary>
88+
89+
[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
90+
91+
Add the following to your [settings.json](https://code.visualstudio.com/docs/copilot/chat/mcp-servers):
92+
93+
```json
94+
{
95+
"mcp": {
96+
"servers": {
97+
"sourcebot": {
98+
"type": "stdio",
99+
"command": "npx",
100+
"args": ["-y", "@sourcebot/mcp@latest"]
101+
},
102+
// Optional - if not specified, https://demo.sourcebot.dev is used
103+
"env": {
104+
"SOURCEBOT_HOST": "http://localhost:3000"
105+
}
106+
}
107+
}
108+
}
109+
```
110+
111+
</details>
112+
113+
<details>
114+
<summary>Claude Code</summary>
115+
116+
[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp)
117+
118+
Run the following command:
119+
120+
```sh
121+
# SOURCEBOT_HOST env var is optional - if not specified,
122+
# https://demo.sourcebot.dev is used.
123+
claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -- npx -y @sourcebot/mcp@latest
124+
```
125+
</details>
126+
127+
<details>
128+
<summary>Claude Desktop</summary>
129+
130+
[Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user)
131+
132+
Add the following to your `claude_desktop_config.json`:
133+
134+
```json
135+
{
136+
"mcpServers": {
137+
"sourcebot": {
138+
"command": "npx",
139+
"args": ["-y", "@sourcebot/mcp@latest"],
140+
// Optional - if not specified, https://demo.sourcebot.dev is used
141+
"env": {
142+
"SOURCEBOT_HOST": "http://localhost:3000"
143+
}
144+
}
145+
}
146+
}
147+
```
148+
</details>
149+
<br/>
150+
151+
4. Tell your LLM to `use sourcebot` when prompting.
152+
153+
<br/>
154+
155+
For a more detailed guide, checkout [the docs](https://docs.sourcebot.dev/docs/more/mcp-server).
156+
157+
158+
## Available Tools
159+
160+
### search_code
161+
162+
Fetches code that matches the provided regex pattern in `query`.
163+
164+
<details>
165+
<summary>Parameters</summary>
166+
167+
| Name | Required | Description |
168+
|:----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------|
169+
| `query` | yes | Regex pattern to search for. Escape special characters and spaces with a single backslash (e.g., 'console\.log', 'console\ log'). |
170+
| `filterByRepoIds` | no | Restrict search to specific repository IDs (from 'list_repos'). Leave empty to search all. |
171+
| `filterByLanguages` | no | Restrict search to specific languages (GitHub linguist format, e.g., Python, JavaScript). |
172+
| `caseSensitive` | no | Case sensitive search (default: false). |
173+
| `includeCodeSnippets` | no | Include code snippets in results (default: false). |
174+
| `maxTokens` | no | Max tokens to return (default: env.DEFAULT_MINIMUM_TOKENS). |
175+
</details>
176+
177+
178+
### list_repos
179+
180+
Lists all repositories indexed by Sourcebot.
181+
182+
### get_file_source
183+
184+
Fetches the source code for a given file.
185+
186+
<details>
187+
<summary>Parameters</summary>
188+
189+
| Name | Required | Description |
190+
|:-------------|:---------|:-----------------------------------------------------------------|
191+
| `fileName` | yes | The file to fetch the source code for. |
192+
| `repoId` | yes | The Sourcebot repository ID. |
193+
</details>
194+
13195

14196
## Supported Code Hosts
15197
Sourcebot supports the following code hosts:
@@ -18,6 +200,20 @@ Sourcebot supports the following code hosts:
18200
- [Bitbucket Cloud](https://docs.sourcebot.dev/docs/connections/bitbucket-cloud)
19201
- [Bitbucket Data Center](https://docs.sourcebot.dev/docs/connections/bitbucket-data-center)
20202
- [Gitea](https://docs.sourcebot.dev/docs/connections/gitea)
21-
- [Gerrit](https://docs.sourcebot.dev/docs/connections/gitea)
203+
- [Gerrit](https://docs.sourcebot.dev/docs/connections/gerrit)
204+
205+
| Don't see your code host? Open a [GitHub discussion](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).
206+
207+
## Future Work
208+
209+
### Semantic Search
210+
211+
Currently, Sourcebot only supports regex-based code search (powered by [zoekt](https://github.com/sourcegraph/zoekt) under the hood). It is great for scenarios when the agent is searching for is something that is super precise and well-represented in the source code (e.g., a specific function name, a error string, etc.). It is not-so-great for _fuzzy_ searches where the objective is to find some loosely defined _category_ or _concept_ in the code (e.g., find code that verifies JWT tokens). The LLM can approximate this by crafting regex searches that attempt to capture a concept (e.g., it might try a query like `"jwt|token|(verify|validate).*(jwt|token)"`), but often yields sub-optimal search results that aren't related. Tools like Cursor solve this with [embedding models](https://docs.cursor.com/context/codebase-indexing) to capture the semantic meaning of code, allowing for LLMs to search using natural language. We would like to extend Sourcebot to support semantic search and expose this capability over MCP as a tool (e.g., `semantic_search_code` tool). [GitHub Discussion](https://github.com/sourcebot-dev/sourcebot/discussions/297)
212+
213+
### Code Navigation
214+
215+
Another idea is to allow LLMs to traverse abstract syntax trees (ASTs) of a codebase to enable reliable code navigation. This could be packaged as tools like `goto_definition`, `find_all_references`, etc., which could be useful for LLMs to get additional code context. [GitHub Discussion](https://github.com/sourcebot-dev/sourcebot/discussions/296)
216+
217+
### Got an idea?
22218

23-
| Don't see your code host? Open a [GitHub discussion](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).
219+
Open up a [GitHub discussion](https://github.com/sourcebot-dev/sourcebot/discussions/categories/feature-requests)!

‎packages/mcp/package.json

Lines changed: 40 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,41 @@
11
{
2-
"name": "@sourcebot/mcp",
3-
"version": "1.0.0",
4-
"type": "module",
5-
"main": "dist/index.js",
6-
"types": "dist/index.d.ts",
7-
"scripts": {
8-
"build": "tsc",
9-
"dev": "node ./dist/index.js",
10-
"build:watch": "tsc-watch --preserveWatchOutput"
11-
},
12-
"devDependencies": {
13-
"@types/express": "^5.0.1",
14-
"@types/node": "^20.0.0",
15-
"tsc-watch": "6.2.1",
16-
"tsx": "^4.0.0",
17-
"typescript": "^5.0.0"
18-
},
19-
"dependencies": {
20-
"@modelcontextprotocol/sdk": "^1.10.2",
21-
"@t3-oss/env-core": "^0.13.4",
22-
"escape-string-regexp": "^5.0.0",
23-
"express": "^5.1.0",
24-
"zod": "^3.24.3"
25-
},
26-
"bin": {
27-
"sourcebot-mcp": "./dist/index.js"
28-
},
29-
"repository": {
30-
"type": "git",
31-
"url": "https://github.com/sourcebot-dev/sourcebot.git",
32-
"directory": "packages/mcp"
33-
}
34-
}
2+
"name": "@sourcebot/mcp",
3+
"version": "1.0.0",
4+
"type": "module",
5+
"main": "dist/index.js",
6+
"types": "dist/index.d.ts",
7+
"scripts": {
8+
"build": "tsc",
9+
"dev": "node ./dist/index.js",
10+
"build:watch": "tsc-watch --preserveWatchOutput"
11+
},
12+
"devDependencies": {
13+
"@types/express": "^5.0.1",
14+
"@types/node": "^20.0.0",
15+
"tsc-watch": "6.2.1",
16+
"tsx": "^4.0.0",
17+
"typescript": "^5.0.0"
18+
},
19+
"dependencies": {
20+
"@modelcontextprotocol/sdk": "^1.10.2",
21+
"@t3-oss/env-core": "^0.13.4",
22+
"escape-string-regexp": "^5.0.0",
23+
"express": "^5.1.0",
24+
"zod": "^3.24.3"
25+
},
26+
"bin": {
27+
"sourcebot-mcp": "./dist/index.js"
28+
},
29+
"repository": {
30+
"type": "git",
31+
"url": "https://github.com/sourcebot-dev/sourcebot.git",
32+
"directory": "packages/mcp"
33+
},
34+
"keywords": [
35+
"mcp",
36+
"modelcontextprotocol",
37+
"code-search",
38+
"sourcebot",
39+
"code-intelligence"
40+
]
41+
}

‎packages/mcp/src/env.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,11 @@ import { z } from "zod";
33

44
export const numberSchema = z.coerce.number();
55

6+
const SOURCEBOT_DEMO_HOST = "https://demo.sourcebot.dev";
7+
68
export const env = createEnv({
79
server: {
8-
SOURCEBOT_HOST: z.string().url().default("http://localhost:3000"),
10+
SOURCEBOT_HOST: z.string().url().default(SOURCEBOT_DEMO_HOST),
911

1012
// The minimum number of tokens to return
1113
DEFAULT_MINIMUM_TOKENS: numberSchema.default(10000),

0 commit comments

Comments
 (0)