Knowledge MCP Server

TypeScript Tests License MCP Compatible

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:

User-level (Global): Applies to all projects
Project-level: Applies to current project only
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

"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

Permission errors

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

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

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:

Large knowledge base: Consider splitting large documents
Git repository size: Archive old projects or use shallow clones
Concurrent operations: File locking ensures safety but may slow bulk operations
Search performance: Use specific keywords instead of broad queries

See Error Handling Guide for detailed debugging information.

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure all tests pass: pnpm run test:all
Run quality checks: pnpm run analyze
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
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

Knowledge MCP Server

🚀 Features

📦 Installation

NPM (Recommended)

From Source

🛠️ Usage

MCP Client Configuration

Claude Desktop Configuration

Direct Execution

🤖 AI Assistant Configuration

⚠️ IMPORTANT CONSTRAINTS

🔍 ERROR CODES

Claude Desktop

Generic MCP Configuration

🔄 Version Management

Why Use @latest and -y Flags

Updating to Latest Version

Configuration Precedence

🛡️ Environment Configuration

Environment Variables

Automatic Project Identification

Storage Structure

Git Remote Setup (Recommended)

📚 API Reference

Core Tools

Project Management

Knowledge Documents

Chapter Iteration

Search & Discovery

TODO Management

Server Operations

Resources

🏗️ Architecture

Storage Structure

Security Features

Concurrency & Performance

🧪 Testing

Test Coverage

🔧 Development

Prerequisites

Development Workflow

Code Quality

📖 Documentation

🐛 Troubleshooting

Common Issues

Debugging with Logs

Error Codes

Verifying Installation

Performance Issues

🤝 Contributing

Development Standards

📄 License

🙏 Acknowledgments

📞 Support

Why Use `@latest` and `-y` Flags