Knowledge MCP Server

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)

npm install -g @spothlynx/knowledge-mcp

From Source

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:

{
  "mcpServers": {
    "knowledge": {
      "command": "knowledge-mcp",
      "args": []
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge": {
      "command": "knowledge-mcp"
    }
  }
}

Direct Execution

# 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 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:

{
  "mcpServers": {
    "knowledge": {
      "command": "npx",
      "args": ["-y", "@spothlynx/knowledge-mcp@latest"]
    }
  }
}

Generic MCP Configuration

For other MCP-compatible clients:

{
  "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

# 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:

# 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:

# 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

# 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 - Complete API reference and architecture
• Error Handling Guide - Error codes and debugging
• MCP Security Guidelines - Security best practices
• Publishing Guidelines - Release and deployment process

🐛 Troubleshooting

Common Issues

1. "spawn npx ENOENT" or "Connection closed"

   # 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

   # Ensure storage directory exists and is writable
   mkdir -p ~/.knowledge-mcp
   chmod 755 ~/.knowledge-mcp
   

3. NPX cache issues

   # 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

   # 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

# 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

# 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 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 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
• Documentation: Technical Specification
• MCP Protocol: Official Documentation

---

Built with ❤️ using TypeScript and the Model Context Protocol