# MCP Bookmarks
Code bookmarks extension for VSCode with MCP (Model Context Protocol) integration, allowing AI assistants to annotate and explain your codebase.
## Features
- **MCP Integration**: Provides MCP tools for AI assistants (Claude Code, Gemini, etc.) to create and manage bookmarks programmatically
- **AI Assistant Support**: AI can analyze your code and create organized bookmarks to explain architecture, flows, and key components
- **Manual Management**: Full support for creating, editing, and organizing bookmarks without AI
- **Hierarchical Bookmarks**: Create parent-child bookmark relationships to represent call chains and code flows
- **Grouped Organization**: Bookmarks are organized into groups by topic, feature, or analysis session
- **Category System**: 4 built-in categories (entry-point, core-logic, issue, note) for clear organization
- **Markdown Link Support**: Cross-reference code locations with clickable links in bookmark descriptions
- **Rich Sidebar**: Interactive webview with tree/nested view modes, search, and filtering
- **Editor Integration**: Inline gutter icons, hover previews, and CodeLens support
- **Quick Navigation**: Jump to bookmarked locations, navigate between bookmarks with keyboard shortcuts
- **Export & Share**: Export bookmarks to Markdown, store in `.vscode/mcp-bookmarks.json` for version control
## Installation
### Method 1: Install from VSIX (Recommended)
1. Download the latest `.vsix` file from [Releases](https://github.com/linonon/mcp-bookmarks/releases)
2. In VSCode, open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
3. Run `Extensions: Install from VSIX...`
4. Select the downloaded `.vsix` file
### Method 2: Install from Source
```bash
# Clone repository
git clone https://github.com/linonon/mcp-bookmarks.git
cd mcp-bookmarks
# Install dependencies and build
npm install
npm run compile
# Package as VSIX
npm run package
# Install the generated .vsix file
code --install-extension mcp-bookmarks-*.vsix
```
## MCP Configuration
After installing the extension, configure MCP integration for your AI tool.
### Quick Setup
1. Open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
2. Run `MCP Bookmarks: Copy MCP Setup Command`
3. Select your AI tool (Claude Code / Gemini / Codex / VSCode)
4. The command will be copied to your clipboard
### For Claude Code Users
Run this command in your terminal (generated by the extension):
```bash
claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"
```
Or manually configure in `.claude/mcp.json`:
```json
{
"mcpServers": {
"mcp-bookmarks": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"],
"description": "MCP Bookmarks - Code annotation and navigation"
}
}
}
```
### For Gemini Users
Run this command in your terminal (generated by the extension):
```bash
gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"
```
### For VSCode MCP Extension Users
1. Press `Cmd+P` (Mac) or `Ctrl+P` (Windows)
2. Type `MCP: Open User Configuration`
3. Add the following configuration:
```json
{
"mcpServers": {
"mcp-bookmarks": {
"type": "stdio",
"command": "node",
"args": ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]
}
}
}
```
### For Codex Users
Paste this snippet into `~/.codex/config.toml`:
```toml
[mcp_servers."mcp-bookmarks"]
command = "node"
args = ["/Users/YOUR_USERNAME/.vscode/mcp-bookmarks-launcher.js"]
```
**Note**: Use the `Copy MCP Setup Command` to get the correct path automatically!
## Usage
### Complete Setup Flow
**Step 1: Install Extension**
```bash
# Download .vsix from GitHub Releases
# Then in VSCode Command Palette:
Extensions: Install from VSIX...
```
**Step 2: Configure MCP (Automatic)**
```bash
# In VSCode Command Palette:
MCP Bookmarks: Copy MCP Setup Command
# Select your AI tool (Claude Code / Gemini / Codex / VSCode)
# Copy the generated command
# For Claude Code, run in terminal:
claude mcp add -s user mcp-bookmarks -- node "~/.vscode/mcp-bookmarks-launcher.js"
# For Gemini, run in terminal:
gemini mcp add -s user mcp-bookmarks node "~/.vscode/mcp-bookmarks-launcher.js"
# For VSCode MCP, paste the path into User Configuration
```
**Step 3: Start Using**
Now your AI assistant can create bookmarks in your codebase!
### Available MCP Tools
- `create_group` - Create a bookmark group
- `add_bookmark` - Add a bookmark to a group
- `batch_add_bookmarks` - Add multiple bookmarks at once
- `list_groups` - List all groups
- `list_bookmarks` - List bookmarks with filters
- `get_group` - Get group details with all bookmarks
- `get_bookmark` - Get single bookmark details
- `update_group` - Update group info
- `update_bookmark` - Update bookmark properties
- `remove_group` - Delete a group and its bookmarks
- `remove_bookmark` - Delete a single bookmark
- `clear_all_bookmarks` - Clear all data (requires confirmation)
### For Users
**Commands:**
- `MCP Bookmarks: Refresh` - Refresh the bookmark tree
- `MCP Bookmarks: Add Bookmark Here` - Manually add a bookmark at cursor
- `MCP Bookmarks: Create Group` - Create a new bookmark group
- `MCP Bookmarks: Edit Group` - Edit group title and description
- `MCP Bookmarks: Rename Group` - Quick rename a group (F2)
- `MCP Bookmarks: Delete Group` - Delete a group and its bookmarks
- `MCP Bookmarks: Edit Bookmark` - Edit bookmark properties
- `MCP Bookmarks: Delete Bookmark` - Delete a bookmark
- `MCP Bookmarks: Move to Group...` - Move bookmark to another group
- `MCP Bookmarks: Move Bookmark Up/Down` - Reorder bookmarks within group
- `MCP Bookmarks: Search Bookmarks` - Search through all bookmarks
- `MCP Bookmarks: Export as Markdown` - Export bookmarks to markdown
- `MCP Bookmarks: Toggle View Mode` - Switch between group/file view
- `MCP Bookmarks: Expand All` - Expand all tree nodes
- `MCP Bookmarks: Collapse All` - Collapse all tree nodes
## Configuration
| Setting | Default | Description |
|---------|---------|-------------|
| `mcpBookmarks.mcpPort` | 3333 | MCP Server port |
| `mcpBookmarks.showInlineDecorations` | true | Show bookmark icons in gutter |
| `mcpBookmarks.viewMode` | "group" | View mode: "group" or "file" |
| `mcpBookmarks.quickAddMode` | "simple" | Quick add mode: "full" (all options) or "simple" (title only) |
| `mcpBookmarks.defaultCategory` | "explanation" | Default category for new bookmarks |
| `mcpBookmarks.confirmBeforeDelete` | true | Show confirmation before deleting |
## Data Storage
Bookmarks are stored in `.vscode/mcp-bookmarks.json` within your workspace. This file can be committed to version control to share bookmarks with your team.
## Development
```bash
# Install dependencies
npm install
# Watch mode (auto-recompile)
npm run watch
# Compile once
npm run compile
# Package extension
npm run package
# Lint
npm run lint
```
## License
MIT
