Minimalist Knowledge Base MCP

Minimalist Knowledge Base 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:

Or run directly with:

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:
   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:
   npm token create
2. Add it to your GitHub repository secrets as NPM_TOKEN.

Manual publish (local)

If you want to publish manually:

Make sure your npm user has access to the @cmwen scope.

Quick Start

1. Start the MCP server for a new knowledge base:
   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 18 or higher
• pnpm (recommended) or npm

Setup

1. Clone the repository:
   git clone git@github.com:cmwen/min-kb-mcp.git cd min-kb-mcp
2. Install dependencies:
   pnpm i
3. Run in development mode:
   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):
   pnpm start -- --kb my-kb
   This is the default mode, suitable for production use with LLM integrations.
2. Development Mode (HTTP):
   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:

Using MCP Inspector

When running in development mode, you can use the MCP Inspector to interact with your server:

1. Start the development server:
   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 for details on our code of conduct and the process for submitting pull requests.

Testing

Run unit tests:

License

This project is licensed under the MIT License - see the LICENSE file for details.