{"_id":"@cmwen/min-kb-mcp","_rev":"2-98a2e09067708d94a325b8b28eff8d27","name":"@cmwen/min-kb-mcp","dist-tags":{"latest":"0.2.3"},"versions":{"0.2.1":{"name":"@cmwen/min-kb-mcp","version":"0.2.1","keywords":["llm","mcp","knowledge-base","sqlite","typescript","markdown","ai","notes"],"author":{"name":"Chi-Ming Wen"},"license":"MIT","_id":"@cmwen/min-kb-mcp@0.2.1","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"homepage":"https://github.com/cmwen/min-kb-mcp#readme","bugs":{"url":"https://github.com/cmwen/min-kb-mcp/issues"},"bin":{"min-kb-mcp":"dist/cli.js"},"dist":{"shasum":"81fd4cdd614aba31d1593dba7aa91711a7b84468","tarball":"https://registry.npmjs.org/@cmwen/min-kb-mcp/-/min-kb-mcp-0.2.1.tgz","fileCount":9,"integrity":"sha512-7iFiYESdx5O76gWLQlXDMHDlpTP+ZNTeUNcjiWcPyhBgDQYuaqq/WvhzqUFUEcO8hV2w682AEY2U22bMhRclMg==","signatures":[{"sig":"MEUCIGHEPQ9139DFg3+CEysfuONnkyEyJrZV1Nhht7pqikujAiEAlZOCKuSHms+Zuli2tYr3U/Nwi5JwjfeKOB7KIgbpi+s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49627},"main":"dist/index.js","_from":"file:cmwen-min-kb-mcp-0.2.1.tgz","engines":{"node":">=18.0.0","pnpm":">=9.0.0"},"scripts":{"dev":"cross-env DEBUG=* MCP_TRANSPORT=http MCP_PORT=9876 tsx --trace-warnings src/cli.ts start --kb dev-kb","lint":"biome check src/","test":"vitest run --reporter=default","build":"tsc","start":"ts-node src/cli.ts","format":"biome format --write src/","lint:fix":"biome check --write src/","test:watch":"vitest"},"_npmUser":{"name":"cmwen","email":"chungmin.wen@gmail.com"},"_resolved":"/tmp/52c712e6e4189a19f6e65d12977c1ebd/cmwen-min-kb-mcp-0.2.1.tgz","_integrity":"sha512-7iFiYESdx5O76gWLQlXDMHDlpTP+ZNTeUNcjiWcPyhBgDQYuaqq/WvhzqUFUEcO8hV2w682AEY2U22bMhRclMg==","repository":{"url":"git+ssh://git@github.com/cmwen/min-kb-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"A minimalist, file-based knowledge base server (MCP) for LLMs.","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.22.4","cors":"^2.8.5","uuid":"^10.0.0","sql.js":"^1.11.0","express":"^5.1.0","commander":"^12.1.0","appdata-path":"^1.0.0","remove-markdown":"^0.5.0","@modelcontextprotocol/sdk":"^1.17.2"},"publishConfig":{"registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.16.2","husky":"^9.1.7","vitest":"^2.0.5","ts-node":"^10.9.2","cross-env":"^10.0.0","typescript":"^5.5.3","@types/cors":"^2.8.19","@types/node":"^20.14.10","@types/uuid":"^10.0.0","@biomejs/biome":"^2.1.4","@types/express":"^5.0.3","@commitlint/cli":"^19.8.1","@types/remove-markdown":"^0.1.1","@commitlint/config-conventional":"^19.8.1"},"_npmOperationalInternal":{"tmp":"tmp/min-kb-mcp_0.2.1_1755774257633_0.7019275592196583","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@cmwen/min-kb-mcp","version":"0.2.3","description":"A minimalist, file-based knowledge base server (MCP) for LLMs.","main":"dist/index.js","types":"dist/index.d.ts","bin":{"min-kb-mcp":"dist/cli.js"},"publishConfig":{"registry":"https://registry.npmjs.org/"},"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","prepublishOnly":"pnpm run build","prepare":"husky"},"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","packageManager":"pnpm@10.14.0","engines":{"node":">=22.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"},"gitHead":"a7d3500d2a1417dfc800969edb94c819077a50d4","_id":"@cmwen/min-kb-mcp@0.2.3","_nodeVersion":"22.21.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-53wfERddrGargBNg7rZds4gkJqZDxepwWlXMStIdaijm6OD2M3TcuKT0t60b9Y90u4xs86hVlNtonenUDvyIHQ==","shasum":"6210f268a9cd1614fcdf9bd9ea6bc8d59565a73b","tarball":"https://registry.npmjs.org/@cmwen/min-kb-mcp/-/min-kb-mcp-0.2.3.tgz","fileCount":22,"unpackedSize":58825,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cmwen%2fmin-kb-mcp@0.2.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCAOF0A0AKRVmKDXu97Ln9nnVMv77cofNJY5beXFSMLwQIhAN+M8k5rmSX+AeRkJxiMARffpA5PQhYmRssN51NZQWrw"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:38fcd3f0-aac6-42f2-baa5-6e64fb6d1aab"}},"directories":{},"maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/min-kb-mcp_0.2.3_1763377828852_0.30419342337955246"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-21T11:04:17.530Z","modified":"2025-11-17T11:10:29.486Z","0.2.1":"2025-08-21T11:04:17.813Z","0.2.3":"2025-11-17T11:10:29.058Z"},"bugs":{"url":"https://github.com/cmwen/min-kb-mcp/issues"},"author":{"name":"Chi-Ming Wen"},"license":"MIT","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"},"description":"A minimalist, file-based knowledge base server (MCP) for LLMs.","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"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/@cmwen/min-kb-mcp.svg)](https://badge.fury.io/js/@cmwen/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. For scoped packages (`@cmwen/*`) the publish command uses `--access public` so your npm user must have permission to publish under the `@cmwen` scope.\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 22 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"}