Knowledge MCP Server

# Knowledge MCP Server [](https://www.typescriptlang.org/) [](#testing) [](LICENSE) [](https://modelcontextprotocol.io/) A production-ready Model Context Protocol (MCP) server that provides centralized knowledge management for AI assistants. Features project-specific documentation, searchable knowledge bases, integrated TODO management, and Git-backed version control for persistent AI memory across sessions. ## 🚀 Features - **📝 Project Knowledge Management**: Centralized storage for project instructions and documentation - **🔍 Advanced Search**: Full-text search across all knowledge documents with contextual results - **📋 TODO System**: Built-in task management with markdown support and progress tracking - **🔐 Security-First**: Comprehensive input validation, path sanitization, and abstraction boundaries - **⚡ High Performance**: Optimized for concurrent operations with sophisticated file locking - **📊 Request Tracing**: Unique trace IDs for debugging and monitoring - **🔄 Git Integration**: Automatic version control with descriptive commit messages - **🧪 Battle-Tested**: 133 comprehensive tests covering all functionality and edge cases ## 📦 Installation ### NPM (Recommended) ```bash npm install -g @spothlynx/knowledge-mcp ``` ### From Source ```bash git clone https://github.com/sven-borkert/knowledge-mcp.git cd knowledge-mcp pnpm install pnpm run build npm link ``` ## 🛠️ Usage ### MCP Client Configuration Add to your MCP client configuration: ```json { "mcpServers": { "knowledge": { "command": "knowledge-mcp", "args": [] } } } ``` ### Claude Desktop Configuration Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "knowledge": { "command": "knowledge-mcp" } } } ``` ### Direct Execution ```bash # Start the MCP server knowledge-mcp # Development mode with auto-reload pnpm run dev ``` ## 🤖 AI Assistant Configuration For comprehensive usage instructions, copy the contents of [`INSTRUCTIONS.md`](INSTRUCTIONS.md) to your global instruction file (e.g., `~/.claude/CLAUDE.md`). This will enable Claude Code to automatically use the Knowledge MCP for all project knowledge management. Knowledge is organized as: ``` ~/.knowledge-mcp/ ├── index.json # Project name mapping ├── activity.log # Request logs (gitignored) └── projects/ └── {project-slug}/ # Auto-detected from git/directory ├── main.md # Project instructions ├── knowledge/ # Knowledge documents │ ├── api-guide.md │ └── architecture.md └── TODO/ # TODO lists └── 1/ # TODO #1 ├── index.md # TODO metadata └── tasks/ # Individual task files ``` ## ⚠️ IMPORTANT CONSTRAINTS - Project ID auto-detected from git repo or current directory name - All paths are sanitized - no `../` or absolute paths - Keywords must be alphanumeric + dots, underscores, hyphens - Maximum 50 chapters per document - File extension `.md` required for knowledge files - Section headers must include `##` prefix (e.g., `"## Configuration"`) - All changes auto-commit with descriptive messages - Storage syncs with origin/main if git remote configured ## 🔍 ERROR CODES Common errors and their meanings: - `PROJECT_NOT_FOUND`: Project doesn't exist yet (use update_project_main to create) - `DOCUMENT_NOT_FOUND`: Knowledge file not found - `FILE_ALREADY_EXISTS`: File/chapter already exists (use update instead) - `CHAPTER_NOT_FOUND`: Chapter title not found in document - `SECTION_NOT_FOUND`: Section header not found in main.md - `TODO_NOT_FOUND`: TODO list doesn't exist - `INVALID_INPUT`: Parameters failed validation - `FILE_SYSTEM_ERROR`: File operation failed - `GIT_ERROR`: Git operation failed Each error includes a `traceId` for debugging. ```` ## 📦 Client-Specific Configuration ### Claude Code ```bash # For global scope (all projects) - ensures latest version is always used claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest # For current project only claude mcp add --scope project knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest # For development (using local build) claude mcp add knowledge-mcp node "$(pwd)/dist/knowledge-mcp/index.js" ```` ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "knowledge": { "command": "npx", "args": ["-y", "@spothlynx/knowledge-mcp@latest"] } } } ``` ### Generic MCP Configuration For other MCP-compatible clients: ```json { "mcpServers": { "knowledge-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@spothlynx/knowledge-mcp@latest"], "env": {} } } } ``` ## 🔄 Version Management ### Why Use `@latest` and `-y` Flags - **`-y` flag**: Automatically accepts npx installation prompt without user interaction - **`@latest` tag**: Forces npx to fetch the newest version instead of using cached versions **Important**: NPX caches packages indefinitely. Without `@latest`, you might run outdated versions. ### Updating to Latest Version ```bash # Remove and re-add to ensure latest version claude mcp remove knowledge-mcp claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest ``` ### Configuration Precedence Most MCP clients support multiple configuration levels: 1. **User-level (Global)**: Applies to all projects 2. **Project-level**: Applies to current project only 3. **Configuration files**: Manual configuration files Higher-level configurations typically override lower-level ones. ## 🛡️ Environment Configuration ### Environment Variables - `KNOWLEDGE_MCP_HOME`: Storage directory (default: `~/.knowledge-mcp`) - `KNOWLEDGE_MCP_LOG_LEVEL`: Log level: `ERROR`, `WARN`, `INFO`, `DEBUG` (default: `INFO`) ### Automatic Project Identification The Knowledge MCP automatically identifies projects based on: - **Git repositories**: Uses repository name from git remote URL - **Non-git directories**: Uses current directory name Example: `/path/to/my-awesome-project/.git` → project_id = "my-awesome-project" ### Storage Structure ``` ~/.knowledge-mcp/ ├── .git/ # Git repository (auto-initialized) ├── index.json # Project name mapping ├── activity.log # Request activity log (gitignored) └── projects/ └── my-app/ ├── main.md # Project instructions (centralized, not in repo) ├── knowledge/ │ ├── api-guide.md # Structured knowledge documents │ └── architecture.md └── TODO/ # TODO lists for the project ├── 1/ # First TODO list │ ├── index.md # TODO metadata │ └── tasks/ # Individual task files └── 2/ # Second TODO list ``` ### Git Remote Setup (Recommended) Enable automatic cloud backup: ```bash # 1. Create repository on GitHub/GitLab # 2. Configure remote cd ~/.knowledge-mcp git remote add origin https://github.com/yourusername/knowledge-mcp-backup.git git push -u origin main # 3. Set up authentication (SSH recommended) git remote set-url origin git@github.com:yourusername/knowledge-mcp-backup.git ``` **⚠️ Important**: On startup, Knowledge MCP pulls from `origin/main` and overwrites local changes. ## 📚 API Reference ### Core Tools #### Project Management - `get_project_main(project_id)` - Retrieve main project instructions - `update_project_main(project_id, content)` - Update project instructions - `update_project_section(project_id, section_header, new_content)` - Update specific section - `add_project_section(project_id, section_header, content, position?, reference_header?)` - Add new section - `remove_project_section(project_id, section_header)` - Remove section - `delete_project(project_id)` - Delete entire project #### Knowledge Documents - `create_knowledge_file(project_id, filename, title, introduction, keywords, chapters)` - Create structured document - `get_knowledge_file(project_id, filename)` - Retrieve complete document - `delete_knowledge_file(project_id, filename)` - Delete document - `update_chapter(project_id, filename, chapter_title, new_content, new_summary?)` - Update chapter - `add_chapter(project_id, filename, chapter_title, content, position?, reference_chapter?)` - Add chapter - `remove_chapter(project_id, filename, chapter_title)` - Remove chapter #### Chapter Iteration - `list_chapters(project_id, filename)` - List all chapters (titles and summaries only) - `get_chapter(project_id, filename, chapter_title | chapter_index)` - Get single chapter content - `get_next_chapter(project_id, filename, current_chapter_title | current_index)` - Get next chapter #### Search & Discovery - `search_knowledge(project_id, query)` - Full-text search across all documents #### TODO Management - `list_todos(project_id)` - List all TODO lists - `create_todo(project_id, description, tasks?)` - Create new TODO list - `get_todo_tasks(project_id, todo_number)` - Get tasks in TODO list - `add_todo_task(project_id, todo_number, title, content?)` - Add task - `complete_todo_task(project_id, todo_number, task_number)` - Mark task complete - `get_next_todo_task(project_id, todo_number)` - Get next incomplete task - `remove_todo_task(project_id, todo_number, task_number)` - Remove task - `delete_todo(project_id, todo_number)` - Delete entire TODO list #### Server Operations - `get_server_info()` - Get server version and configuration - `get_storage_status()` - Get Git repository status - `sync_storage()` - Force Git commit and sync ### Resources The server provides read-only resources for browsing: - `knowledge://projects/{project_id}/main` - Project main instructions - `knowledge://projects/{project_id}/files` - List of knowledge files - `knowledge://projects/{project_id}/chapters/{filename}` - Chapter listings ## 🏗️ Architecture ### Storage Structure ``` ~/.knowledge-mcp/ ├── index.json # Project name to directory mapping ├── activity.log # Request activity log (gitignored) └── projects/ └── {project-slug}/ # Slugified project directory ├── main.md # Main project instructions ├── knowledge/ # Knowledge documents │ └── *.md # Individual knowledge files └── TODO/ # TODO lists └── {number}/ # Numbered TODO directories ├── index.md # TODO metadata └── tasks/ # Individual task files └── *.md ``` ### Security Features - **Path Validation**: Prevents directory traversal attacks - **Input Sanitization**: Comprehensive validation with Zod schemas - **Abstraction Boundaries**: Internal paths never exposed to clients - **Atomic Operations**: File operations use temp-file + rename pattern - **Request Tracing**: Unique trace IDs for all operations ### Concurrency & Performance - **File Locking**: Queue-based locking prevents race conditions - **Atomic Updates**: All file operations are atomic - **Efficient Search**: Optimized full-text search with result limiting - **Memory Management**: Controlled memory usage for large documents ## 🧪 Testing The project includes comprehensive test coverage: ```bash # Run all tests pnpm run test:all # Run specific test suite npx tsx test/suites/01-project-main.test.ts # Generate HTML test report pnpm run test:all && open test-results/html/merged-results.html ``` ### Test Coverage - **133 tests** across 11 comprehensive test suites - **100% success rate** in CI/CD pipeline - **Edge cases** including concurrency, unicode, and error conditions - **Security tests** for abstraction boundaries and input validation - **Performance tests** for high-load scenarios ## 🔧 Development ### Prerequisites - Node.js 18+ - pnpm (recommended) or npm - TypeScript 5.7+ ### Development Workflow ```bash # Install dependencies pnpm install # Start development server with auto-reload pnpm run dev # Build for production pnpm run build # Run type checking pnpm run type-check # Run linter pnpm run lint # Format code pnpm run format # Run all quality checks pnpm run analyze ``` ### Code Quality The project enforces high code quality standards: - **TypeScript**: Strict mode with comprehensive type checking - **ESLint**: Comprehensive linting with TypeScript support - **Prettier**: Consistent code formatting - **Static Analysis**: Zero warnings policy - **Test Coverage**: All functionality thoroughly tested ## 📖 Documentation - **[Technical Specification](docs/technical-specification.md)** - Complete API reference and architecture - **[Error Handling Guide](docs/error-handling-guide.md)** - Error codes and debugging - **[MCP Security Guidelines](docs/mcp-security-guidelines.md)** - Security best practices - **[Publishing Guidelines](docs/publishing-guidelines.md)** - Release and deployment process ## 🐛 Troubleshooting ### Common Issues 1. **"spawn npx ENOENT" or "Connection closed"** ```bash # Remove and re-add to ensure latest version claude mcp remove knowledge-mcp claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest ``` 2. **Permission errors** ```bash # Ensure storage directory exists and is writable mkdir -p ~/.knowledge-mcp chmod 755 ~/.knowledge-mcp ``` 3. **NPX cache issues** ```bash # Clear NPX cache if using published version rm -rf ~/.npm/_npx # Reinstall with @latest claude mcp remove knowledge-mcp claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest ``` 4. **Version conflicts** ```bash # Check all configuration scopes claude mcp list # Remove from all scopes and re-add claude mcp remove knowledge-mcp -s global claude mcp remove knowledge-mcp -s project claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest ``` ### Debugging with Logs ```bash # View MCP logs (location varies by client) # For Claude Code: ls ~/Library/Caches/claude-cli-nodejs/*/mcp-logs-knowledge-mcp/ # View activity logs with trace IDs tail -f ~/.knowledge-mcp/activity.log # Check Git repository status cd ~/.knowledge-mcp && git status ``` ### Error Codes The Knowledge MCP uses standardized error codes for debugging: - `PROJECT_NOT_FOUND` - Project doesn't exist yet (call `update_project_main` to create) - `DOCUMENT_NOT_FOUND` - Knowledge file not found - `FILE_ALREADY_EXISTS` - File already exists (use update instead of create) - `SECTION_NOT_FOUND` - Section header not found in document - `SECTION_ALREADY_EXISTS` - Section header already exists - `INVALID_INPUT` - Invalid parameters (check Zod validation errors) - `TODO_NOT_FOUND` - TODO list doesn't exist - `TODO_TASK_NOT_FOUND` - Task not found in TODO list - `FILE_SYSTEM_ERROR` - File operation failed - `GIT_ERROR` - Git operation failed Each error includes a unique `traceId` for debugging. Search logs using: `grep "traceId" ~/.knowledge-mcp/activity.log` ### Verifying Installation ```bash # Check if Knowledge MCP is properly configured claude mcp list | grep knowledge-mcp # Test basic functionality (if using Claude Code) # Should return server information /mcp knowledge get_server_info # Verify storage directory ls -la ~/.knowledge-mcp/ ``` ### Performance Issues If experiencing slow performance: 1. **Large knowledge base**: Consider splitting large documents 2. **Git repository size**: Archive old projects or use shallow clones 3. **Concurrent operations**: File locking ensures safety but may slow bulk operations 4. **Search performance**: Use specific keywords instead of broad queries See [Error Handling Guide](docs/error-handling-guide.md) for detailed debugging information. ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/amazing-feature` 3. Make your changes and add tests 4. Ensure all tests pass: `pnpm run test:all` 5. Run quality checks: `pnpm run analyze` 6. Commit your changes: `git commit -m 'Add amazing feature'` 7. Push to the branch: `git push origin feature/amazing-feature` 8. Open a Pull Request ### Development Standards - All new features must include comprehensive tests - Code must pass all static analysis checks - Documentation must be updated for API changes - Security considerations must be addressed ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🙏 Acknowledgments - **Model Context Protocol** - For the excellent MCP specification - **TypeScript Community** - For outstanding tooling and ecosystem - **Contributors** - For making this project better ## 📞 Support - **Issues**: [GitHub Issues](https://github.com/sven-borkert/knowledge-mcp/issues) - **Documentation**: [Technical Specification](docs/technical-specification.md) - **MCP Protocol**: [Official Documentation](https://modelcontextprotocol.io/) --- **Built with ❤️ using TypeScript and the Model Context Protocol**