Skip to content

Commit 7261ec8

Browse files
DevanshuNEUDevanshuNEU
committed
docs: Add comprehensive MCP setup guide and documentation system
- Add /docs route with DocsLayout and sidebar navigation - Create MCPSetupPage with full MCP integration guide - Create DocsHomePage with feature overview - Add docs/MCP_SETUP.md for GitHub reference - Update App.tsx with public docs routes (no auth required) - Update build script to separate TypeScript checks Includes: - Step-by-step Claude Desktop configuration - All 6 MCP tools with example prompts - OS-specific config paths (macOS, Windows, Linux) - Troubleshooting section - Conversational, developer-friendly tone Closes #64
1 parent 545c8e5 commit 7261ec8

10 files changed

Lines changed: 1056 additions & 56 deletions

File tree

‎README.md‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -140,30 +140,40 @@ curl -X POST http://localhost:8000/api/repos \
140140

141141
## MCP Integration
142142

143-
CodeIntel works as an MCP server with Claude Desktop:
143+
CodeIntel works as an MCP server with Claude Desktop. **[📚 Full MCP Setup Guide](./docs/MCP_SETUP.md)**
144+
145+
**Quick Setup:**
144146

145147
```json
146-
// Add to Claude Desktop config (~/.config/claude/config.json)
148+
// Add to Claude Desktop config
147149
{
148150
"mcpServers": {
149151
"codeintel": {
150152
"command": "python",
151-
"args": ["/path/to/pebble/mcp-server/server.py"]
153+
"args": ["/path/to/opencodeintel/mcp-server/server.py"],
154+
"env": {
155+
"BACKEND_API_URL": "http://localhost:8000",
156+
"API_KEY": "your-api-key"
157+
}
152158
}
153159
}
154160
}
155161
```
156162

157163
**Available MCP Tools:**
158-
- `search_code` - Semantic code search
159-
- `list_repositories` - View indexed repos
160-
- `get_dependency_graph` - Analyze architecture
161-
- `analyze_code_style` - Team patterns
162-
- `analyze_impact` - Change impact prediction
163-
- `get_repository_insights` - Comprehensive metrics
164+
| Tool | Description |
165+
|------|-------------|
166+
| `search_code` | Semantic code search - finds code by meaning |
167+
| `list_repositories` | View all indexed repos |
168+
| `get_dependency_graph` | Visualize architecture and file connections |
169+
| `analyze_code_style` | Team conventions and patterns |
170+
| `analyze_impact` | Know what breaks before you change it |
171+
| `get_repository_insights` | High-level codebase overview |
164172

165173
Now ask Claude: *"What's the authentication logic in the user service?"* and it searches your actual codebase.
166174

175+
**[→ Complete setup guide with troubleshooting](./docs/MCP_SETUP.md)**
176+
167177
## Architecture
168178

169179
```

‎docs/MCP_SETUP.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# MCP Setup Guide
2+
3+
Most AI coding assistants forget your codebase the moment you close the chat. You explain your auth flow, close the window, come back tomorrow - and Claude has no idea what you're talking about.
4+
5+
CodeIntel fixes this. It's an MCP server that gives Claude (or any MCP-compatible AI) persistent memory of your entire codebase - semantic search, dependency graphs, impact analysis, the works.
6+
7+
Here's how to set it up in under 5 minutes.
8+
9+
---
10+
11+
## What is MCP?
12+
13+
MCP (Model Context Protocol) is Anthropic's open standard for connecting AI assistants to external tools and data sources. Think of it as USB for AI - a universal way to plug in capabilities.
14+
15+
Instead of copy-pasting code into Claude, MCP lets Claude directly search your codebase, analyze dependencies, and understand impact of changes.
16+
17+
**The result?** Claude that actually knows your code.
18+
19+
---
20+
21+
## Prerequisites
22+
23+
Before you start, make sure you have:
24+
25+
- **Claude Desktop** installed ([download here](https://claude.ai/download))
26+
- **CodeIntel backend** running (either locally or hosted)
27+
- **Python 3.11+** for the MCP server
28+
- **5 minutes** of your time
29+
30+
---
31+
32+
## Setup Steps
33+
34+
### Step 1: Clone the MCP Server
35+
36+
If you haven't already, grab the CodeIntel repo:
37+
38+
```bash
39+
git clone https://github.com/OpenCodeIntel/opencodeintel.git
40+
cd opencodeintel/mcp-server
41+
```
42+
43+
### Step 2: Install Dependencies
44+
45+
```bash
46+
pip install -r requirements.txt
47+
```
48+
49+
That's it. No virtual environment drama for a simple MCP server.
50+
51+
### Step 3: Configure Environment
52+
53+
Create your `.env` file:
54+
55+
```bash
56+
cp .env.example .env
57+
```
58+
59+
Edit `.env` with your settings:
60+
61+
```env
62+
# Where's your CodeIntel backend running?
63+
BACKEND_API_URL=http://localhost:8000
64+
65+
# Your API key (get this from the CodeIntel dashboard)
66+
API_KEY=your-api-key-here
67+
```
68+
69+
**Using hosted CodeIntel?** Replace `localhost:8000` with your hosted URL.
70+
71+
### Step 4: Configure Claude Desktop
72+
73+
This is where the magic happens. You need to tell Claude Desktop about the MCP server.
74+
75+
**Find your config file:**
76+
77+
| OS | Config Location |
78+
|----|-----------------|
79+
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
80+
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
81+
| Linux | `~/.config/Claude/claude_desktop_config.json` |
82+
83+
**Add CodeIntel to your config:**
84+
85+
```json
86+
{
87+
"mcpServers": {
88+
"codeintel": {
89+
"command": "python",
90+
"args": ["/absolute/path/to/opencodeintel/mcp-server/server.py"],
91+
"env": {
92+
"BACKEND_API_URL": "http://localhost:8000",
93+
"API_KEY": "your-api-key-here"
94+
}
95+
}
96+
}
97+
}
98+
```
99+
100+
> ⚠️ **Important:** Use the absolute path to `server.py`. Relative paths won't work.
101+
102+
**Example for macOS:**
103+
```json
104+
{
105+
"mcpServers": {
106+
"codeintel": {
107+
"command": "python3",
108+
"args": ["/Users/yourname/projects/opencodeintel/mcp-server/server.py"],
109+
"env": {
110+
"BACKEND_API_URL": "http://localhost:8000",
111+
"API_KEY": "dev-secret-key"
112+
}
113+
}
114+
}
115+
}
116+
```
117+
118+
### Step 5: Restart Claude Desktop
119+
120+
Completely quit Claude Desktop (not just close the window) and reopen it.
121+
122+
You should see a 🔧 icon in the chat input - that means MCP tools are available.
123+
124+
---
125+
126+
## Available Tools
127+
128+
Once connected, Claude has access to these tools:
129+
130+
### `search_code`
131+
Semantic search across your codebase. Finds code by meaning, not just keywords.
132+
133+
```
134+
"Find authentication middleware"
135+
"Show me error handling patterns"
136+
"Where's the database connection logic?"
137+
```
138+
139+
### `list_repositories`
140+
See all indexed repositories.
141+
142+
```
143+
"What repos do you have access to?"
144+
"List my codebases"
145+
```
146+
147+
### `get_dependency_graph`
148+
Understand how files connect. See which files are critical (many dependents) vs isolated.
149+
150+
```
151+
"Show me the dependency graph for this repo"
152+
"What files does auth.py depend on?"
153+
```
154+
155+
### `analyze_code_style`
156+
Team patterns: naming conventions, async usage, type hints, common imports.
157+
158+
```
159+
"What coding conventions does this repo use?"
160+
"Is this team using snake_case or camelCase?"
161+
```
162+
163+
### `analyze_impact`
164+
Before you change a file, know what breaks. Shows direct dependents, indirect impact, and related tests.
165+
166+
```
167+
"What happens if I modify src/auth/middleware.py?"
168+
"What's the blast radius of changing this file?"
169+
```
170+
171+
### `get_repository_insights`
172+
High-level overview: file count, critical files, architecture patterns.
173+
174+
```
175+
"Give me an overview of this codebase"
176+
"What are the most important files here?"
177+
```
178+
179+
---
180+
181+
## Example Prompts
182+
183+
Here's how to actually use CodeIntel with Claude:
184+
185+
**Understanding new code:**
186+
> "I just joined this project. Search for the main entry points and explain the architecture."
187+
188+
**Before refactoring:**
189+
> "I want to refactor UserService. What's the impact? What tests cover it?"
190+
191+
**Finding patterns:**
192+
> "How does this codebase handle errors? Find examples of error handling."
193+
194+
**Code review prep:**
195+
> "Search for all usages of the deprecated `oldAuth()` function."
196+
197+
**Matching team style:**
198+
> "Analyze the code style. I want to write a new module that fits in."
199+
200+
---
201+
202+
## Troubleshooting
203+
204+
### Claude doesn't show the 🔧 icon
205+
206+
1. **Check the config path** - Make sure you're editing the right config file
207+
2. **Validate JSON** - A single missing comma breaks everything
208+
3. **Use absolute paths** - Relative paths don't work
209+
4. **Restart fully** - Quit Claude Desktop completely, not just close window
210+
211+
### "Connection refused" errors
212+
213+
Your CodeIntel backend isn't running. Start it:
214+
215+
```bash
216+
cd opencodeintel/backend
217+
python main.py
218+
```
219+
220+
### "Unauthorized" errors
221+
222+
Check your `API_KEY` in both:
223+
- The `.env` file in `mcp-server/`
224+
- The Claude Desktop config
225+
226+
They need to match what your backend expects.
227+
228+
### Tools work but return no results
229+
230+
You probably haven't indexed any repositories yet. Open the CodeIntel dashboard and add a repo first.
231+
232+
### Python command not found
233+
234+
On macOS, you might need `python3` instead of `python`:
235+
236+
```json
237+
{
238+
"command": "python3",
239+
"args": ["/path/to/server.py"]
240+
}
241+
```
242+
243+
---
244+
245+
## What's Next?
246+
247+
Once you're set up:
248+
249+
1. **Index a repository** through the CodeIntel dashboard
250+
2. **Start chatting** with Claude about your code
251+
3. **Try impact analysis** before your next refactor
252+
253+
Questions? Issues? [Open a GitHub issue](https://github.com/OpenCodeIntel/opencodeintel/issues) or reach out.
254+
255+
---
256+
257+
*Built because AI assistants shouldn't have amnesia about your code.*

0 commit comments

Comments
 (0)