Skip to content

Commit 1014324

Browse files
jgravellejgravelle
authored
Update installation instructions and improve clarity
1 parent bc5370c commit 1014324

File tree

1 file changed

+64
-34
lines changed

1 file changed

+64
-34
lines changed

‎USER_GUIDE.md‎

Lines changed: 64 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,19 @@
33
## Installation
44

55
```bash
6-
pip install jcodemunch-mcp
6+
pip install git+https://github.com/jgravelle/jcodemunch-mcp.git
77
```
88

99
Or from source:
10+
1011
```bash
11-
git clone https://github.com/jcodemunch/jcodemunch-mcp.git
12+
git clone https://github.com/jgravelle/jcodemunch-mcp.git
1213
cd jcodemunch-mcp
1314
pip install -e .
1415
```
1516

17+
---
18+
1619
## Configuration
1720

1821
### Claude Desktop
@@ -33,7 +36,10 @@ Add to your `claude_desktop_config.json`:
3336
}
3437
```
3538

36-
Both environment variables are optional — `GITHUB_TOKEN` enables private repos and higher rate limits, `ANTHROPIC_API_KEY` enables AI-generated summaries.
39+
Both environment variables are optional:
40+
41+
* `GITHUB_TOKEN` enables private repositories and higher GitHub API rate limits.
42+
* `ANTHROPIC_API_KEY` enables AI-generated summaries (otherwise docstrings or signatures are used).
3743

3844
### VS Code
3945

@@ -52,6 +58,8 @@ Add to `.vscode/settings.json`:
5258
}
5359
```
5460

61+
---
62+
5563
## Workflows
5664

5765
### Explore a New Repository
@@ -67,8 +75,8 @@ get_file_outline: { "repo": "fastapi/fastapi", "file_path": "fastapi/main.py" }
6775

6876
```
6977
index_folder: { "path": "/home/user/myproject" }
70-
get_repo_outline: { "repo": "local/myproject" }
71-
search_symbols: { "repo": "local/myproject", "query": "main" }
78+
get_repo_outline: { "repo": "local-myproject" }
79+
search_symbols: { "repo": "local-myproject", "query": "main" }
7280
```
7381

7482
### Find and Read a Function
@@ -101,15 +109,15 @@ get_symbol: {
101109
}
102110
```
103111

104-
The response `_meta.content_verified` will be `true` if the source matches the stored hash, `false` if it has drifted.
112+
The response `_meta.content_verified` will be `true` if the source matches the stored hash and `false` if it has drifted.
105113

106114
### Search for Non-Symbol Content
107115

108116
```
109117
search_text: { "repo": "owner/repo", "query": "TODO", "file_pattern": "*.py" }
110118
```
111119

112-
Use `search_text` for string literals, comments, config values, or anything that isn't a symbol name.
120+
Use `search_text` for string literals, comments, configuration values, or anything that is not a symbol name.
113121

114122
### Force Re-index
115123

@@ -118,25 +126,35 @@ invalidate_cache: { "repo": "owner/repo" }
118126
index_repo: { "url": "owner/repo" }
119127
```
120128

129+
---
130+
121131
## Tool Reference
122132

123-
| Tool | Purpose | Key Parameters |
124-
|------|---------|---------------|
125-
| `index_repo` | Index GitHub repo | `url`, `use_ai_summaries` |
126-
| `index_folder` | Index local folder | `path`, `extra_ignore_patterns`, `follow_symlinks` |
127-
| `list_repos` | List all indexed repos | — |
128-
| `get_file_tree` | Browse file structure | `repo`, `path_prefix` |
129-
| `get_file_outline` | Symbols in a file | `repo`, `file_path` |
130-
| `get_symbol` | Full source of one symbol | `repo`, `symbol_id`, `verify`, `context_lines` |
131-
| `get_symbols` | Batch retrieve symbols | `repo`, `symbol_ids` |
132-
| `search_symbols` | Search symbols | `repo`, `query`, `kind`, `language`, `file_pattern`, `max_results` |
133-
| `search_text` | Full-text search | `repo`, `query`, `file_pattern`, `max_results` |
134-
| `get_repo_outline` | High-level overview | `repo` |
135-
| `invalidate_cache` | Delete cached index | `repo` |
133+
| Tool | Purpose | Key Parameters |
134+
| ------------------ | ----------------------------- | ------------------------------------------------------------------ |
135+
| `index_repo` | Index GitHub repository | `url`, `use_ai_summaries` |
136+
| `index_folder` | Index local folder | `path`, `extra_ignore_patterns`, `follow_symlinks` |
137+
| `list_repos` | List all indexed repositories | — |
138+
| `get_file_tree` | Browse file structure | `repo`, `path_prefix` |
139+
| `get_file_outline` | Symbols in a file | `repo`, `file_path` |
140+
| `get_symbol` | Full source of one symbol | `repo`, `symbol_id`, `verify`, `context_lines` |
141+
| `get_symbols` | Batch retrieve symbols | `repo`, `symbol_ids` |
142+
| `search_symbols` | Search symbols | `repo`, `query`, `kind`, `language`, `file_pattern`, `max_results` |
143+
| `search_text` | Full-text search | `repo`, `query`, `file_pattern`, `max_results` |
144+
| `get_repo_outline` | High-level overview | `repo` |
145+
| `invalidate_cache` | Delete cached index | `repo` |
146+
147+
---
136148

137149
## Symbol IDs
138150

139-
Symbol IDs follow the format `{file_path}::{qualified_name}#{kind}`:
151+
Symbol IDs follow the format:
152+
153+
```
154+
{file_path}::{qualified_name}#{kind}
155+
```
156+
157+
Examples:
140158

141159
```
142160
src/main.py::UserService#class
@@ -147,23 +165,33 @@ config.py::MAX_RETRIES#constant
147165

148166
IDs are returned by `get_file_outline`, `search_symbols`, and `search_text`. Pass them to `get_symbol` or `get_symbols` to retrieve source code.
149167

168+
---
169+
150170
## Troubleshooting
151171

152-
**"Repository not found"** — Check the URL format (`owner/repo` or full GitHub URL). For private repos, set `GITHUB_TOKEN`.
172+
**"Repository not found"**
173+
Check the URL format (`owner/repo` or full GitHub URL). For private repositories, set `GITHUB_TOKEN`.
174+
175+
**"No source files found"**
176+
The repository may not contain supported language files (`.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`), or files may be excluded by skip patterns.
153177

154-
**"No source files found"** — The repo may not contain supported language files (.py, .js, .ts, .go, .rs, .java), or files may be in skip patterns.
178+
**Rate limiting**
179+
Set `GITHUB_TOKEN` to increase GitHub API limits (5,000 requests/hour vs 60 unauthenticated).
155180

156-
**Rate limiting** — Set `GITHUB_TOKEN` for 5,000 requests/hour (vs 60 without).
181+
**AI summaries not working**
182+
Set `ANTHROPIC_API_KEY`. Without it, summaries fall back to docstrings or signatures.
157183

158-
**AI summaries not working** — Set `ANTHROPIC_API_KEY`. Without it, summaries fall back to docstrings or signatures.
184+
**Stale index**
185+
Use `invalidate_cache` followed by `index_repo` or `index_folder` to force a clean re-index.
159186

160-
**Stale index** — Use `invalidate_cache` followed by `index_repo` or `index_folder` to force a clean re-index.
187+
**Encoding issues**
188+
Files with invalid UTF-8 are handled safely using replacement characters.
161189

162-
**Encoding issues** — Files with invalid UTF-8 are handled gracefully with replacement characters.
190+
---
163191

164192
## Storage
165193

166-
Indexes live at `~/.code-index/` (override with `CODE_INDEX_PATH` env var):
194+
Indexes are stored at `~/.code-index/` (override with the `CODE_INDEX_PATH` environment variable):
167195

168196
```
169197
~/.code-index/
@@ -172,11 +200,13 @@ Indexes live at `~/.code-index/` (override with `CODE_INDEX_PATH` env var):
172200
└── src/main.py
173201
```
174202

203+
---
204+
175205
## Tips
176206

177-
1. **Start with `get_repo_outline`** for a quick lay of the land
178-
2. **Use `get_file_outline`** before reading source — understand the API first
179-
3. **Filter searches** with `kind`, `language`, and `file_pattern` to narrow results
180-
4. **Batch retrieve** related symbols with `get_symbols` instead of multiple `get_symbol` calls
181-
5. **Use `search_text`** when symbol search misses — it searches actual file content
182-
6. **Use `verify: true`** on `get_symbol` to detect source drift since indexing
207+
1. Start with `get_repo_outline` to quickly understand the repository structure.
208+
2. Use `get_file_outline` before reading source to understand the API surface first.
209+
3. Narrow searches using `kind`, `language`, and `file_pattern`.
210+
4. Batch-retrieve related symbols with `get_symbols` instead of repeated `get_symbol` calls.
211+
5. Use `search_text` when symbol search does not locate the needed content.
212+
6. Use `verify: true` on `get_symbol` to detect source drift since indexing.

0 commit comments

Comments
 (0)