{"_id":"@cmw1n/min-kb-mcp","name":"@cmw1n/min-kb-mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@cmw1n/min-kb-mcp","version":"0.2.0","description":"A minimalist, file-based knowledge base server (MCP) for LLMs.","main":"dist/index.js","bin":{"min-kb-mcp":"dist/cli.js"},"publishConfig":{"registry":"https://registry.npmjs.org/"},"keywords":["llm","mcp","knowledge-base","sqlite","typescript","markdown","ai","notes"],"repository":{"type":"git","url":"git+ssh://git@github.com/cmwen/min-kb-mcp.git"},"bugs":{"url":"https://github.com/cmwen/min-kb-mcp/issues"},"homepage":"https://github.com/cmwen/min-kb-mcp#readme","author":{"name":"Chi-Ming Wen"},"license":"MIT","engines":{"node":">=18.0.0","pnpm":">=9.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.2","appdata-path":"^1.0.0","sql.js":"^1.11.0","commander":"^12.1.0","cors":"^2.8.5","express":"^5.1.0","remove-markdown":"^0.5.0","uuid":"^10.0.0","zod":"^3.22.4"},"devDependencies":{"@biomejs/biome":"^2.1.4","@commitlint/cli":"^19.8.1","@commitlint/config-conventional":"^19.8.1","@types/node":"^20.14.10","vitest":"^2.0.5","@types/cors":"^2.8.19","@types/express":"^5.0.3","@types/remove-markdown":"^0.1.1","@types/uuid":"^10.0.0","cross-env":"^10.0.0","husky":"^9.1.7","ts-node":"^10.9.2","tsx":"^4.16.2","typescript":"^5.5.3"},"scripts":{"start":"ts-node src/cli.ts","dev":"cross-env DEBUG=* MCP_TRANSPORT=http MCP_PORT=9876 tsx --trace-warnings src/cli.ts start --kb dev-kb","build":"tsc","lint":"biome check src/","lint:fix":"biome check --write src/","format":"biome format --write src/","test":"vitest run --reporter=default","test:watch":"vitest"},"_id":"@cmw1n/min-kb-mcp@0.2.0","_integrity":"sha512-l4ltFDnukqq1q+RU0/ghYMfzVSMrRp5p+X2Yw7NtlnmSEYIQ9ANk1Q5CMV7oJ8FMFYlGi8/PE3Vzg/xYyL6Ovg==","_resolved":"/private/var/folders/4x/kf9hg09938g4v_9crwvvxp5w0000gn/T/e993d9a4e95baee3fc141533a90dbefb/cmw1n-min-kb-mcp-0.2.0.tgz","_from":"file:cmw1n-min-kb-mcp-0.2.0.tgz","_nodeVersion":"22.7.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-l4ltFDnukqq1q+RU0/ghYMfzVSMrRp5p+X2Yw7NtlnmSEYIQ9ANk1Q5CMV7oJ8FMFYlGi8/PE3Vzg/xYyL6Ovg==","shasum":"4ac196d65654feed547eb577355bddfa9fc19ec9","tarball":"https://registry.npmjs.org/@cmw1n/min-kb-mcp/-/min-kb-mcp-0.2.0.tgz","fileCount":11,"unpackedSize":57897,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGg963bhEDUbQr/yhgK+EsQjDIjklmIwdR8YX5cN4dgEAiEA3cBVg7qb5ERGmBWxZCLex9iGFbyoYrYCd5Z4nbLG9m8="}]},"_npmUser":{"name":"cmw1n","email":"chungminwen@hotmail.com"},"directories":{},"maintainers":[{"name":"cmw1n","email":"chungminwen@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/min-kb-mcp_0.2.0_1754815930757_0.05542505814223353"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-10T08:52:10.657Z","0.2.0":"2025-08-10T08:52:11.007Z","modified":"2025-08-10T08:52:11.266Z"},"maintainers":[{"name":"cmw1n","email":"chungminwen@hotmail.com"}],"description":"A minimalist, file-based knowledge base server (MCP) for LLMs.","homepage":"https://github.com/cmwen/min-kb-mcp#readme","keywords":["llm","mcp","knowledge-base","sqlite","typescript","markdown","ai","notes"],"repository":{"type":"git","url":"git+ssh://git@github.com/cmwen/min-kb-mcp.git"},"author":{"name":"Chi-Ming Wen"},"bugs":{"url":"https://github.com/cmwen/min-kb-mcp/issues"},"license":"MIT","readme":"# Minimalist Knowledge Base MCP\n\n[![CI](https://github.com/cmwen/min-kb-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cmwen/min-kb-mcp/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/min-kb-mcp.svg)](https://badge.fury.io/js/min-kb-mcp)\n\nA 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.\n\n## Features\n\n- Multi-Knowledge Base Support: manage multiple independent knowledge bases\n- Storage model:\n   - Markdown files as the source of truth\n   - SQLite database (WASM via sql.js) for indexing/search — zero native dependencies\n- Full-Text Search: attempts SQLite FTS5; falls back to LIKE-based search if FTS5 isn’t available in the WASM build\n- Cross-Platform: works on Windows, macOS, and Linux (npx with no extra config)\n- LLM-First Design: built specifically for LLM interaction via MCP\n\n## Installation\n\n\nZero native deps (no compilers, no SDKs). To install from npm:\n\n```bash\npnpm add @cmwen/min-kb-mcp\n```\n\nOr run directly with:\n\n```bash\nnpx @cmwen/min-kb-mcp start --kb my-notes\n```\n\n## Publishing to npm\n\nTo publish a new version:\n\n1. Bump the version in `package.json`.\n2. Commit and push your changes.\n3. Create a new tag (e.g. `v1.2.3`) and push it:\n   ```bash\n   git tag v1.2.3\n   git push origin v1.2.3\n   ```\n4. The GitHub Actions workflow will automatically build and publish to npm if you have set the `NPM_TOKEN` secret in your repository.\n\n### Setting up your npm token\n\n1. Get your npm token by running:\n   ```bash\n   npm token create\n   ```\n2. Add it to your GitHub repository secrets as `NPM_TOKEN`.\n\n### Manual publish (local)\n\nIf you want to publish manually:\n\n```bash\npnpm run build\npnpm publish --access public\n```\n\nMake sure your npm user has access to the `@cmwen` scope.\n\n## Quick Start\n\n1) Start the MCP server for a new knowledge base:\n\n   ```bash\n   npx @cmwen/min-kb-mcp start --kb my-notes\n   ```\n\n2) The server will create:\n   - A directory for your knowledge base in the standard application support location\n   - A SQLite database for indexing\n   - An articles directory for markdown files\n\n## Storage Structure\n\nFiles are stored in your system's standard application support directory:\n\n- macOS: `~/Library/Application Support/min-kb-mcp/<kb-name>/`\n- Linux: `~/.local/share/min-kb-mcp/<kb-name>/`\n- Windows: `%APPDATA%\\\\min-kb-mcp\\\\<kb-name>\\\\`\n\nEach knowledge base contains:\n\n- `<kb-name>.sqlite`: The SQLite database file\n- `articles/`: Directory containing markdown files\n\n## MCP Tools\n\nThe following tools are available to LLMs through the MCP server:\n\n- `createArticle`: Create a new article with content and optional keywords\n- `getArticle`: Retrieve an article by ID\n- `updateArticle`: Update an existing article's content and keywords\n- `deleteArticle`: Delete an article\n- `searchArticles`: Full-text search with optional time filters\n- `findLinkedArticles`: Find articles sharing keywords\n- `getArticlesByTimeRange`: Get articles within a time range\n- `listArticles`: List all articles\n- `getArticleStats`: Get statistics about the knowledge base\n\n## Development\n\n### Prerequisites\n\n- Node.js 18 or higher\n- pnpm (recommended) or npm\n\n### Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone git@github.com:cmwen/min-kb-mcp.git\n   cd min-kb-mcp\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pnpm i\n   ```\n\n3. Run in development mode:\n   ```bash\n   pnpm start -- --kb test-kb\n   ```\n\n### Scripts\n\n- `pnpm start`: Start the MCP server in stdio mode\n- `pnpm run dev`: Start the development server with HTTP transport on port 9876\n- `pnpm run build`: Build the TypeScript code\n- `pnpm run lint`: Lint with Biome\n- `pnpm run format`: Format with Biome\n- `pnpm test`: Run unit tests (Vitest)\n- `pnpm run test:watch`: Watch tests\n\n### Development Server\n\nThe project supports two transport modes:\n\n1. **Standard Mode (stdio)**:\n\n   ```bash\n   pnpm start -- --kb my-kb\n   ```\n\n   This is the default mode, suitable for production use with LLM integrations.\n\n2. **Development Mode (HTTP)**:\n   ```bash\n   pnpm run dev\n   ```\n   This starts a development server that:\n   - Uses HTTP transport instead of stdio\n   - Runs on port 9876\n   - Creates a 'dev-kb' knowledge base\n   - Enables CORS for browser clients\n   - Supports multiple concurrent connections\n   - Provides better debugging capabilities\n\nYou can also customize the transport mode and port using environment variables:\n\n```bash\nMCP_TRANSPORT=http MCP_PORT=3000 pnpm start -- --kb my-kb\n```\n\n### Using MCP Inspector\n\nWhen running in development mode, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to interact with your server:\n\n1. Start the development server:\n\n   ```bash\n   pnpm run dev\n   ```\n\n2. Open MCP Inspector and connect to:\n   ```\n   http://localhost:9876/mcp\n   ```\n\nThe inspector allows you to:\n\n- Browse available tools and resources\n- Execute tools with different parameters\n- View server responses and error messages\n- Test server functionality interactively\n\nThis is particularly useful for:\n\n- Development and debugging\n- Testing new features\n- Understanding tool behavior\n- Verifying error handling\n\n## Portability and FTS notes\n\n- The database runs on WebAssembly using sql.js — no native builds required.\n- 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).\n- 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.\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## Testing\n\nRun unit tests:\n\n```bash\npnpm test\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md","_rev":"1-5d1a4650c2548c40dad3e128bdf23ae8"}