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:

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Provides centralized knowledge management for projects, allowing users to store, search, and maintain project-specific knowledge that persists across sessions.

Related MCP Servers

Memory MCP Server
evangstav
-
security
A
license
-
quality
Provides knowledge graph functionality for managing entities, relations, and observations in memory with strict validation rules to maintain data consistency.
Last updated -
16
Python
MIT License
Project MCP Server
tejpalvirk
A
security
F
license
A
quality
Provides tools for managing project knowledge graphs, enabling structured representation of projects, tasks, milestones, resources, and team members.
Last updated -
6
7
TypeScript
Student MCP Server
tejpalvirk
A
security
F
license
A
quality
Provides tools for managing student knowledge graphs, enabling structured representation of courses, assignments, exams, concepts, and study resources.
Last updated -
6
TypeScript
Memory Bank MCP
tuncer-byte
A
security
F
license
A
quality
An MCP server that helps teams create, manage, and access structured project documentation through six core document types, leveraging AI to generate comprehensive project knowledge management.
Last updated -
5
21
97
TypeScript

View all related MCP servers