Skip to main content
Glama

Knowledge MCP Server

by sven-borkert

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

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

🐛 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


Built with ❤️ using TypeScript and the Model Context Protocol

Related MCP Servers

  • -
    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
  • 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
    • Apple
    • Linux
  • 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
    • Apple
    • Linux
  • 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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sven-borkert/knowledge-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server