|
1 | | -# bucketeer-docs-local-mcp-server |
2 | | -Local MCP Server to query Bucketeer documentation |
| 1 | +# Bucketeer Docs Local MCP Server |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This project provides a Model Context Protocol (MCP) server for Bucketeer documentation. It offers an interface for searching and retrieving content from Bucketeer's feature flag and experimentation platform documentation, enabling AI assistants to provide accurate information about Bucketeer's features and usage. |
| 6 | + |
| 7 | +## Environment Setup |
| 8 | + |
| 9 | +### Requirements |
| 10 | + |
| 11 | +- Node.js 18+ |
| 12 | +- npm |
| 13 | + |
| 14 | +### Installation Steps |
| 15 | + |
| 16 | +1. Clone the repository: |
| 17 | + |
| 18 | +```bash |
| 19 | +git clone <repository-url> |
| 20 | +cd bucketeer-docs-local-mcp-server |
| 21 | +``` |
| 22 | + |
| 23 | +2. Install dependencies: |
| 24 | + |
| 25 | +```bash |
| 26 | +npm install |
| 27 | +``` |
| 28 | + |
| 29 | +3. Build the project: |
| 30 | + |
| 31 | +```bash |
| 32 | +npm run build |
| 33 | +``` |
| 34 | + |
| 35 | +4. Build the document index: |
| 36 | + |
| 37 | +```bash |
| 38 | +npm run build:index |
| 39 | +``` |
| 40 | + |
| 41 | +## Starting the Server |
| 42 | + |
| 43 | +```bash |
| 44 | +npm start |
| 45 | +``` |
| 46 | + |
| 47 | +## Document Sources |
| 48 | + |
| 49 | +The server automatically fetches and indexes documentation from the [bucketeer-io/bucketeer-docs](https://github.com/bucketeer-io/bucketeer-docs) repository: |
| 50 | + |
| 51 | +- **GitHub Repository Integration**: |
| 52 | + - Automatically fetches `.mdx` files from the `docs/` directory and all subdirectories |
| 53 | + - Processes frontmatter and markdown content for optimal search indexing |
| 54 | + - Caches fetched content using SHA hashes and only updates when files are modified |
| 55 | + - Supports recursive directory traversal to capture all documentation files |
| 56 | + |
| 57 | +- **Intelligent Indexing**: |
| 58 | + - Extracts keywords from titles, descriptions, headers, and content |
| 59 | + - Builds searchable index with relevance scoring based on keyword matches and full-text search |
| 60 | + - Optimized for Bucketeer-specific terminology (feature flags, experiments, SDKs, targeting, etc.) |
| 61 | + - Handles frontmatter extraction (title, description) from MDX files |
| 62 | + |
| 63 | +- **Cache Management**: |
| 64 | + - Files are cached locally in `files/docs/` directory as JSON files |
| 65 | + - Document index is stored in `files/index/document-index.json` |
| 66 | + - GitHub cache stored in `files/docs/github_cache.json` with SHA-based change detection |
| 67 | + - Use `npm run build:index:force` to force rebuild the entire index |
| 68 | + |
| 69 | +## Cursor and Claude Desktop Configuration |
| 70 | + |
| 71 | +### Setup |
| 72 | + |
| 73 | +Configure the MCP Server by adding the following to your `mcp.json` or `claude_desktop_config.json` file, referring to the documentation for Cursor (https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) and Claude Desktop (https://modelcontextprotocol.io/quickstart/user): |
| 74 | + |
| 75 | +```json |
| 76 | +{ |
| 77 | + "mcpServers": { |
| 78 | + "bucketeer-docs": { |
| 79 | + "command": "node", |
| 80 | + "args": ["/path/to/bucketeer-docs-local-mcp-server/dist/main.js"] |
| 81 | + } |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +**Important**: Make sure to use the absolute path to the `dist/main.js` file after building the project. |
| 87 | + |
| 88 | +## Usage |
| 89 | + |
| 90 | +When the MCP server is running, the following tools are available: |
| 91 | + |
| 92 | +### 1. `search-docs` - Search Bucketeer Documentation |
| 93 | +- **Parameter**: `query` (string) - The search query |
| 94 | +- **Parameter**: `limit` (number, optional) - Maximum number of results to return (default: 5) |
| 95 | + |
| 96 | +**Example**: |
| 97 | +```json |
| 98 | +{ |
| 99 | + "name": "search-docs", |
| 100 | + "arguments": { |
| 101 | + "query": "feature flags SDK integration", |
| 102 | + "limit": 5 |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +**Response**: Returns an array of search results with title, URL, path, description, excerpt, and relevance score. |
| 108 | + |
| 109 | +### 2. `get-document` - Get Specific Document Content |
| 110 | +- **Parameter**: `path` (string) - Document path obtained from search results |
| 111 | + |
| 112 | +**Example**: |
| 113 | +```json |
| 114 | +{ |
| 115 | + "name": "get-document", |
| 116 | + "arguments": { |
| 117 | + "path": "getting-started/create-feature-flag" |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +**Response**: Returns the full document content including title, description, URL, and complete markdown content. |
| 123 | + |
| 124 | + |
| 125 | +## Development Commands |
| 126 | + |
| 127 | +- `npm run build` - Compile TypeScript files to `dist/` directory |
| 128 | +- `npm run build:index` - Build/update the document index from GitHub repository |
| 129 | +- `npm run build:index:force` - Force rebuild the entire index (ignores cache) |
| 130 | +- `npm run dev:index` - Build and update index in development mode |
| 131 | +- `npm run dev` - Build and start server in development mode |
| 132 | + |
| 133 | +## Configuration |
| 134 | + |
| 135 | +The server is configured via `src/config/index.ts`: |
| 136 | + |
| 137 | +- **siteName**: "Bucketeer" |
| 138 | +- **websiteUrl**: "https://docs.bucketeer.io" |
| 139 | +- **githubRepo**: "https://github.com/bucketeer-io/bucketeer-docs" |
| 140 | +- **docsDirectory**: "docs" (directory in GitHub repo containing documentation) |
| 141 | +- **searchLimitDefault**: 5 (default number of search results) |
| 142 | +- **useGithubSource**: true (always uses GitHub as source) |
| 143 | + |
| 144 | +## File Structure |
| 145 | + |
| 146 | +``` |
| 147 | +files/ |
| 148 | +├── docs/ # Cached JSON files from GitHub repository |
| 149 | +├── index/ # Document search index |
| 150 | +│ └── document-index.json |
| 151 | +└── [created automatically when building index] |
| 152 | +``` |
| 153 | + |
| 154 | +## Architecture |
| 155 | + |
| 156 | +The server consists of several key components: |
| 157 | + |
| 158 | +1. **GithubDocumentFetcher**: Recursively fetches `.mdx` files from the GitHub repository |
| 159 | +2. **IndexManager**: Builds and manages the searchable document index |
| 160 | +3. **SearchService**: Provides search functionality with keyword matching and full-text search |
| 161 | +4. **MCP Server**: Exposes tools via the Model Context Protocol |
| 162 | + |
| 163 | +## Contributing |
| 164 | + |
| 165 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 166 | + |
| 167 | +## License |
| 168 | + |
| 169 | +MIT |
0 commit comments