min-kb-mcp

# Minimalist Knowledge Base MCP [](https://github.com/cmwen/min-kb-mcp/actions/workflows/ci.yml) [](https://badge.fury.io/js/@cmwen/min-kb-mcp) A minimalist, file-based knowledge base server designed to be operated programmatically by Large Language Models (LLMs) and developers. It functions as a headless MCP (Model Context Protocol) server, exposing a suite of tools for managing knowledge. ## Features - Multi-Knowledge Base Support: manage multiple independent knowledge bases - Storage model: - Markdown files as the source of truth - SQLite database (WASM via sql.js) for indexing/search — zero native dependencies - Full-Text Search: attempts SQLite FTS5; falls back to LIKE-based search if FTS5 isn’t available in the WASM build - Cross-Platform: works on Windows, macOS, and Linux (npx with no extra config) - LLM-First Design: built specifically for LLM interaction via MCP ## Installation Zero native deps (no compilers, no SDKs). To install from npm: ```bash pnpm add @cmwen/min-kb-mcp ``` Or run directly with: ```bash npx @cmwen/min-kb-mcp start --kb my-notes ``` ## Publishing to npm To publish a new version: 1. Bump the version in `package.json`. 2. Commit and push your changes. 3. Create a new tag (e.g. `v1.2.3`) and push it: ```bash git tag v1.2.3 git push origin v1.2.3 ``` 4. The GitHub Actions workflow will automatically build and publish to npm if you have set the `NPM_TOKEN` secret in your repository. For scoped packages (`@cmwen/*`) the publish command uses `--access public` so your npm user must have permission to publish under the `@cmwen` scope. ### Setting up your npm token 1. Get your npm token by running: ```bash npm token create ``` 2. Add it to your GitHub repository secrets as `NPM_TOKEN`. ### Manual publish (local) If you want to publish manually: ```bash pnpm run build pnpm publish --access public ``` Make sure your npm user has access to the `@cmwen` scope. ## Quick Start 1) Start the MCP server for a new knowledge base: ```bash npx @cmwen/min-kb-mcp start --kb my-notes ``` 2) The server will create: - A directory for your knowledge base in the standard application support location - A SQLite database for indexing - An articles directory for markdown files ## Storage Structure Files are stored in your system's standard application support directory: - macOS: `~/Library/Application Support/min-kb-mcp/<kb-name>/` - Linux: `~/.local/share/min-kb-mcp/<kb-name>/` - Windows: `%APPDATA%\\min-kb-mcp\\<kb-name>\\` Each knowledge base contains: - `<kb-name>.sqlite`: The SQLite database file - `articles/`: Directory containing markdown files ## MCP Tools The following tools are available to LLMs through the MCP server: - `createArticle`: Create a new article with content and optional keywords - `getArticle`: Retrieve an article by ID - `updateArticle`: Update an existing article's content and keywords - `deleteArticle`: Delete an article - `searchArticles`: Full-text search with optional time filters - `findLinkedArticles`: Find articles sharing keywords - `getArticlesByTimeRange`: Get articles within a time range - `listArticles`: List all articles - `getArticleStats`: Get statistics about the knowledge base ## Development ### Prerequisites - Node.js 22 or higher - pnpm (recommended) or npm ### Setup 1. Clone the repository: ```bash git clone git@github.com:cmwen/min-kb-mcp.git cd min-kb-mcp ``` 2. Install dependencies: ```bash pnpm i ``` 3. Run in development mode: ```bash pnpm start -- --kb test-kb ``` ### Scripts - `pnpm start`: Start the MCP server in stdio mode - `pnpm run dev`: Start the development server with HTTP transport on port 9876 - `pnpm run build`: Build the TypeScript code - `pnpm run lint`: Lint with Biome - `pnpm run format`: Format with Biome - `pnpm test`: Run unit tests (Vitest) - `pnpm run test:watch`: Watch tests ### Development Server The project supports two transport modes: 1. **Standard Mode (stdio)**: ```bash pnpm start -- --kb my-kb ``` This is the default mode, suitable for production use with LLM integrations. 2. **Development Mode (HTTP)**: ```bash pnpm run dev ``` This starts a development server that: - Uses HTTP transport instead of stdio - Runs on port 9876 - Creates a 'dev-kb' knowledge base - Enables CORS for browser clients - Supports multiple concurrent connections - Provides better debugging capabilities You can also customize the transport mode and port using environment variables: ```bash MCP_TRANSPORT=http MCP_PORT=3000 pnpm start -- --kb my-kb ``` ### Using MCP Inspector When running in development mode, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to interact with your server: 1. Start the development server: ```bash pnpm run dev ``` 2. Open MCP Inspector and connect to: ``` http://localhost:9876/mcp ``` The inspector allows you to: - Browse available tools and resources - Execute tools with different parameters - View server responses and error messages - Test server functionality interactively This is particularly useful for: - Development and debugging - Testing new features - Understanding tool behavior - Verifying error handling ## Portability and FTS notes - The database runs on WebAssembly using sql.js — no native builds required. - We attempt to enable FTS5 (with porter tokenizer if available). If the WASM build doesn’t provide FTS5, the server falls back to a simple LIKE-based search. In that case, ranking values may be 0 and ordering may differ from FTS5 ranking (bm25). - For most small to medium note sets, the WASM backend is sufficient. If you need maximum performance, you could adapt a native backend, but this project prioritizes zero-config portability by default. ## Contributing Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## Testing Run unit tests: ```bash pnpm test ``` ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.