INSTALL.md•5.2 kB
# Breadcrumb MCP Server - Installation & Setup Guide
This guide will help you install and configure the Breadcrumb MCP server for use with Claude Code.
## Prerequisites
- Python 3.10 or higher
- Claude Code installed
- Access to Claude Code settings
## Installation
### 1. Install the MCP Server
From the breadcrumb repository root:
```bash
cd mcp-server
pip install -e .
```
This will install the `breadcrumb-mcp` package in editable mode.
### 2. Verify Installation
```bash
python3 -m breadcrumb_mcp.server --version
```
## Configuration
### Claude Code MCP Settings
You need to configure Claude Code to use the Breadcrumb MCP server.
#### Option 1: Using Claude Code UI
1. Open Claude Code settings
2. Navigate to MCP Servers section
3. Click "Add MCP Server"
4. Enter the configuration (see below)
#### Option 2: Manual Configuration
Edit your Claude Code configuration file (usually at `~/.config/claude/mcp_settings.json` or similar):
```json
{
"mcpServers": {
"breadcrumb": {
"command": "python3",
"args": ["-m", "breadcrumb_mcp.server"],
"env": {
"BREADCRUMB_ROOT": "/Users/hoangd/breadcrumb"
}
}
}
}
```
**Important:** Replace `/Users/hoangd/breadcrumb` with the actual path to your breadcrumb repository.
### Environment Variables
- `BREADCRUMB_ROOT` (required): Absolute path to the breadcrumb repository root
## Usage in Claude Code
Once configured, you can use breadcrumb tools and resources in Claude Code:
### Using Tools
Tools appear as available functions that Claude can call:
```
# Create a new project
mcp__breadcrumb__create_project(name="my-app", language_stack="Python, FastAPI", purpose="API backend")
# Search documentation
mcp__breadcrumb__search_breadcrumbs(query="authentication", project="my-app")
# Add a learning
mcp__breadcrumb__add_learning(project="my-app", learning="JWT tokens expire after 1 hour")
# Get recent sessions
mcp__breadcrumb__get_recent_sessions(project="my-app", limit=3)
```
### Using Resources
Resources can be read directly:
```
# Read project index
breadcrumb://project/my-app/index
# Read a session
breadcrumb://project/my-app/sessions/2025-01-15-auth-refactor.md
# List all projects
breadcrumb://projects
```
## Available Tools
### Project Management
- `create_project` - Create new project structure
- `list_projects` - List all projects
- `get_project_info` - Get project information
- `get_project_stats` - Get project statistics
### Documentation Creation
- `create_session` - Create session log
- `create_component` - Create component documentation
- `create_adr` - Create Architectural Decision Record
- `create_pattern` - Create pattern documentation
### Search & Discovery
- `search_breadcrumbs` - Search across documentation
- `find_related_docs` - Find related documents
- `list_tags` - List all tags with counts
- `get_timeline` - Get activity timeline
### Quick Updates
- `add_learning` - Add learning to project index
- `quick_note` - Add timestamped note
- `update_project_status` - Update project status
- `get_recent_sessions` - Get recent session logs
## Troubleshooting
### Server Not Starting
Check Python version:
```bash
python3 --version # Should be 3.10 or higher
```
Check installation:
```bash
pip show breadcrumb-mcp
```
### Tools Not Appearing
1. Verify MCP configuration is correct
2. Restart Claude Code
3. Check Claude Code logs for errors
### Path Issues
Make sure `BREADCRUMB_ROOT` points to the correct directory:
```bash
ls $BREADCRUMB_ROOT/templates # Should list template files
```
### Permission Issues
Ensure the breadcrumb directory is readable and writable:
```bash
ls -la $BREADCRUMB_ROOT
```
## Development
### Running Tests
```bash
cd mcp-server
pytest
```
### Debugging
Set Python logging to DEBUG:
```json
{
"mcpServers": {
"breadcrumb": {
"command": "python3",
"args": ["-m", "breadcrumb_mcp.server"],
"env": {
"BREADCRUMB_ROOT": "/path/to/breadcrumb",
"PYTHONPATH": "/path/to/breadcrumb/mcp-server/src",
"LOG_LEVEL": "DEBUG"
}
}
}
}
```
### Making Changes
The server is installed in editable mode (`pip install -e .`), so changes to the source code take effect immediately after restarting Claude Code.
## Migrating from Bash Scripts
If you were previously using bash scripts:
| Bash Script | MCP Tool |
|-------------|----------|
| `./scripts/new-project.sh` | `create_project` |
| `./scripts/breadcrumb-search.sh` | `search_breadcrumbs` |
| `./scripts/new-session.sh` | `create_session` |
| `./scripts/breadcrumb-update.sh add-learning` | `add_learning` |
| `./scripts/breadcrumb-index.sh stats` | `get_project_stats` |
The MCP server provides the same functionality with better integration into Claude Code.
## Next Steps
1. Create your first project: Use `create_project` tool
2. Read the project index: Use `breadcrumb://project/{name}/index` resource
3. Start documenting: Use `create_session` to log your work
4. Search when needed: Use `search_breadcrumbs` to find information
## Support
For issues or questions:
- Check the main README.md
- Review the CLAUDE.md for usage guidance
- Open an issue in the repository