feat: init implementation

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run lint
+        run: npm run lint
+
+      - name: Run tests
+        run: npm run test:ci

.gitignore

@@ -1,136 +1,46 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-.pnpm-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
+# Dependencies
 node_modules/
-jspm_packages/
+npm-debug.log
 
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
 
-# TypeScript cache
+# Build output
+build/
+dist/
+*.js.map
+
+# TypeScript compiled files
 *.tsbuildinfo
 
-# Optional npm cache directory
+# Cache files
 .npm
-
-# Optional eslint cache
 .eslintcache
 
-# Optional stylelint cache
-.stylelintcache
-
-# Microbundle cache
-.rpt2_cache/
-.rts2_cache_cjs/
-.rts2_cache_es/
-.rts2_cache_umd/
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
+# Environment variables
 .env
+.env.local
 .env.development.local
 .env.test.local
 .env.production.local
-.env.local
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
 
-# vuepress build output
-.vuepress/dist
+# OS specific files
+.DS_Store
+Thumbs.db
 
-# vuepress v2.x temp and cache directory
-.temp
-.cache
+# Editor directories and files
+.idea/
+.vscode/
+*.swp
+*.swo
 
-# vitepress build output
-**/.vitepress/dist
+# Temporary directories
+tmp/
+temp/
 
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# TernJS port file
-.tern-port
+# Logs
+logs/
+*.log
+npm-debug.log*
 
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
+# Files
+files/
 
-# yarn v2
-.yarn/cache
-.yarn/unplugged
-.yarn/build-state.yml
-.yarn/install-state.gz
-.pnp.*

LICENSE

@@ -199,3 +199,4 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+

README.md

@@ -1,2 +1,169 @@
-# bucketeer-docs-local-mcp-server
-Local MCP Server to query Bucketeer documentation
+# Bucketeer Docs Local MCP Server
+
+## Overview
+
+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.
+
+## Environment Setup
+
+### Requirements
+
+- Node.js 18+
+- npm
+
+### Installation Steps
+
+1. Clone the repository:
+
+```bash
+git clone <repository-url>
+cd bucketeer-docs-local-mcp-server
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Build the project:
+
+```bash
+npm run build
+```
+
+4. Build the document index:
+
+```bash
+npm run build:index
+```
+
+## Starting the Server
+
+```bash
+npm start
+```
+
+## Document Sources
+
+The server automatically fetches and indexes documentation from the [bucketeer-io/bucketeer-docs](https://github.com/bucketeer-io/bucketeer-docs) repository:
+
+- **GitHub Repository Integration**: 
+  - Automatically fetches `.mdx` files from the `docs/` directory and all subdirectories
+  - Processes frontmatter and markdown content for optimal search indexing
+  - Caches fetched content using SHA hashes and only updates when files are modified
+  - Supports recursive directory traversal to capture all documentation files
+
+- **Intelligent Indexing**:
+  - Extracts keywords from titles, descriptions, headers, and content
+  - Builds searchable index with relevance scoring based on keyword matches and full-text search
+  - Optimized for Bucketeer-specific terminology (feature flags, experiments, SDKs, targeting, etc.)
+  - Handles frontmatter extraction (title, description) from MDX files
+
+- **Cache Management**:
+  - Files are cached locally in `files/docs/` directory as JSON files
+  - Document index is stored in `files/index/document-index.json`
+  - GitHub cache stored in `files/docs/github_cache.json` with SHA-based change detection
+  - Use `npm run build:index:force` to force rebuild the entire index
+
+## Cursor and Claude Desktop Configuration
+
+### Setup
+
+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):
+
+```json
+{
+  "mcpServers": {
+    "bucketeer-docs": {
+      "command": "node",
+      "args": ["/path/to/bucketeer-docs-local-mcp-server/dist/main.js"]
+    }
+  }
+}
+```
+
+**Important**: Make sure to use the absolute path to the `dist/main.js` file after building the project.
+
+## Usage
+
+When the MCP server is running, the following tools are available:
+
+### 1. `search-docs` - Search Bucketeer Documentation
+- **Parameter**: `query` (string) - The search query
+- **Parameter**: `limit` (number, optional) - Maximum number of results to return (default: 5)
+
+**Example**:
+```json
+{
+  "name": "search-docs",
+  "arguments": {
+    "query": "feature flags SDK integration",
+    "limit": 5
+  }
+}
+```
+
+**Response**: Returns an array of search results with title, URL, path, description, excerpt, and relevance score.
+
+### 2. `get-document` - Get Specific Document Content
+- **Parameter**: `path` (string) - Document path obtained from search results
+
+**Example**:
+```json
+{
+  "name": "get-document",
+  "arguments": {
+    "path": "getting-started/create-feature-flag"
+  }
+}
+```
+
+**Response**: Returns the full document content including title, description, URL, and complete markdown content.
+
+
+## Development Commands
+
+- `npm run build` - Compile TypeScript files to `dist/` directory
+- `npm run build:index` - Build/update the document index from GitHub repository
+- `npm run build:index:force` - Force rebuild the entire index (ignores cache)
+- `npm run dev:index` - Build and update index in development mode
+- `npm run dev` - Build and start server in development mode
+
+## Configuration
+
+The server is configured via `src/config/index.ts`:
+
+- **siteName**: "Bucketeer"
+- **websiteUrl**: "https://docs.bucketeer.io"
+- **githubRepo**: "https://github.com/bucketeer-io/bucketeer-docs"
+- **docsDirectory**: "docs" (directory in GitHub repo containing documentation)
+- **searchLimitDefault**: 5 (default number of search results)
+- **useGithubSource**: true (always uses GitHub as source)
+
+## File Structure
+
+```
+files/
+├── docs/           # Cached JSON files from GitHub repository
+├── index/          # Document search index
+│   └── document-index.json
+└── [created automatically when building index]
+```
+
+## Architecture
+
+The server consists of several key components:
+
+1. **GithubDocumentFetcher**: Recursively fetches `.mdx` files from the GitHub repository
+2. **IndexManager**: Builds and manages the searchable document index
+3. **SearchService**: Provides search functionality with keyword matching and full-text search
+4. **MCP Server**: Exposes tools via the Model Context Protocol
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

biome.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "ignore": ["dist/**"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "ignore": ["dist/**"]
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingComma": "es5",
+      "semicolons": "always"
+    }
+  }
+}