Skip to main content
Glama

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

Related MCP server: Memory Bank MCP

📦 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

Available Tools

27 tools
add_chapterAdd ChapterA

Add a new chapter to an existing knowledge document with positioning control.

When to use this tool:

  • Expanding document with new topics

  • Adding examples or case studies

  • Including additional reference material

  • Inserting clarifying chapters

  • Growing documentation organically

Key features:

  • Flexible positioning (before/after/end)

  • Maintains document flow

  • Maximum 50 chapters per document

  • Reference-based positioning

You should:

  1. Choose clear, descriptive chapter titles

  2. Position chapter logically in document flow

  3. Keep chapters focused on single topics

  4. Use reference_chapter for precise placement

  5. Consider reader's journey through document

  6. Check current chapter count (max 50)

  7. Include practical, actionable content

DO NOT use when:

  • Chapter already exists

  • Document has 50 chapters already

  • Content belongs in existing chapter

Position options: "before", "after", "end" (default) Returns: {success: bool, message?: str, error?: str}

Inputs: chapter_title (required), content (required), filename (required), project_id (required), +2 more.

add_project_sectionAdd Project SectionA

Add a new section to the project main.md file with precise positioning control.

When to use this tool:

  • Introducing new topics or guidelines to project

  • Expanding project documentation systematically

  • Adding configuration sections

  • Creating new instruction categories

  • Organizing content into new logical groups

Key features:

  • Flexible positioning (before/after/end)

  • Maintains document structure and flow

  • Non-destructive addition

  • Reference-based positioning for precision

You should:

  1. Choose meaningful section headers with "## " prefix

  2. Decide optimal position for the new section

  3. Use reference_header for precise placement

  4. Keep sections focused on single topics

  5. Follow existing section naming conventions

  6. Consider document flow and readability

  7. Add sections progressively, not all at once

DO NOT use when:

  • Section already exists (use update_project_section)

  • Content belongs in existing section

  • Unsure about section organization

Position options: "before", "after", "end" (default) Returns: {success: bool, message?: str, error?: str}

Inputs: content (required), project_id (required), section_header (required), position, +1 more.

add_todo_taskAdd TODO TaskA

Add a new task to an existing TODO list with full markdown support.

When to use this tool:

  • Expanding existing TODO with new tasks

  • Adding discovered subtasks during work

  • Including additional requirements

  • Appending follow-up tasks

  • Adding clarifications or details

Key features:

  • Full markdown support in content

  • Can include code blocks and examples

  • Auto-incrementing task numbers

  • Preserves existing task order

  • Rich formatting capabilities

You should:

  1. Verify TODO exists first

  2. Use clear, actionable task titles (max 200 chars)

  3. Include implementation details in content

  4. Add code examples where helpful

  5. Position task logically in sequence

  6. Keep task scope focused

  7. Use markdown formatting effectively

DO NOT use when:

  • TODO doesn't exist

  • Task duplicates existing one

  • Task is too vague or broad

Returns: {success: bool, task_number: int, message: str, error?: str}

Inputs: project_id (required), title (required), todo_number (required), content.

complete_todo_taskComplete TODO TaskA

Mark a task as completed in a TODO list.

When to use this tool:

  • Task implementation is fully complete

  • Task requirements are met

  • Moving to next task in sequence

  • Updating progress status

  • Recording completion for tracking

Key features:

  • Marks task with completion timestamp

  • Updates TODO completion percentage

  • Preserves task content and history

  • Cannot be undone

You should:

  1. ONLY mark complete when truly finished

  2. Verify task is actually done

  3. Test/validate before marking complete

  4. Complete tasks as you finish them

  5. Don't batch completions

  6. Move to next task after completing

DO NOT use when:

  • Task is partially complete

  • Work is blocked or paused

  • Need to revisit later

  • Implementation failed

Returns: {success: bool, message: str, error?: str}

Inputs: project_id (required), task_number (required), todo_number (required).

create_knowledge_fileCreate Knowledge FileA

Create a structured knowledge document with rich metadata and chapters.

When to use this tool:

  • Documenting specific technical topics or APIs

  • Creating reference guides for project components

  • Building troubleshooting or how-to guides

  • Organizing domain-specific knowledge

  • Archiving important technical decisions

Key features:

  • Structured with chapters for easy navigation

  • Searchable via keywords

  • Automatic filename sanitization (spaces→hyphens)

  • Metadata for context and discovery

  • Supports up to 50 chapters per document

You should:

  1. Search first to avoid creating duplicates

  2. Choose descriptive, specific filenames

  3. Include 3-5 relevant keywords minimum

  4. Structure content into logical chapters

  5. Write clear chapter titles (max 200 chars)

  6. Include practical examples in content

  7. Add .md extension to filename

  8. Keep chapters focused and concise

  9. Consider future searchability

DO NOT use when:

  • Content belongs in main.md

  • Document already exists (search first!)

  • Information is temporary or transient

  • Creating index/navigation files

Chapters require 'title' and 'content' keys Returns: {success: bool, document_id?: str, message?: str, error?: str}

Inputs: chapters (required), filename (required), introduction (required), keywords (required), +2 more.

create_todoCreate TODOA

Create a new TODO list with optional initial tasks and rich markdown support.

When to use this tool:

  • User explicitly requests "create a TODO"

  • Planning multi-step implementation tasks

  • Organizing feature development work

  • Tracking bug fixes or improvements

  • Creating task lists for later execution

Key features:

  • Rich markdown support in task content

  • Optional initial task list

  • Auto-incrementing TODO numbers

  • Task content supports code blocks

  • Hierarchical task organization

You should:

  1. ONLY create when user explicitly requests

  2. Include clear, actionable task descriptions

  3. Break complex work into subtasks

  4. Use markdown for code examples in tasks

  5. Number tasks logically

  6. Keep descriptions concise but complete

  7. Group related tasks together

DO NOT use when:

  • User hasn't explicitly asked for TODO

  • Tasks are trivial or single-step

  • Work will be done immediately

  • TODO already exists for this work

Tasks need {title: str, content?: str} format Returns: {success: bool, todo_number: int, message: str, error?: str}

Inputs: description (required), project_id (required), tasks.

delete_knowledge_fileDelete Knowledge FileA

Permanently delete a knowledge document - this action cannot be undone.

When to use this tool:

  • Document is obsolete or incorrect

  • Consolidating duplicate documents

  • Removing outdated information

  • Explicit request to delete

Key features:

  • Complete removal of document

  • Removes from search index

  • Permanent deletion

You should:

  1. Verify document exists first

  2. Check if content should be preserved elsewhere

  3. Confirm filename is correct (with .md extension)

  4. Understand deletion is permanent

  5. Consider if update would be better

DO NOT use when:

  • Document might be useful later

  • Should be updated instead

  • Unsure about the impact

Returns: {success: bool, message?: str, error?: str}

Inputs: filename (required), project_id (required).

delete_projectDelete ProjectA

Permanently delete a project and all its content - USE WITH EXTREME CAUTION.

When to use this tool:

  • Project is completely obsolete

  • Cleaning up test or temporary projects

  • Project has been migrated elsewhere

  • Explicit user request to delete

Key features:

  • Removes entire project directory

  • Deletes from index

  • IRREVERSIBLE operation

  • Includes all knowledge files and TODOs

You should:

  1. ALWAYS confirm with user before deletion

  2. Verify project_id is correct

  3. Consider backing up important content first

  4. Understand this is permanent

  5. Check if project has valuable knowledge files

  6. Document reason for deletion

DO NOT use when:

  • Any doubt about deletion

  • Project might be needed later

  • Haven't backed up important content

  • User hasn't explicitly confirmed

⚠️ This action CANNOT be undone! Returns: {success: bool, project_id: str, message: str, error?: str}

Inputs: project_id (required).

delete_todoDelete TODOA

Delete an entire TODO list and all its tasks permanently.

When to use this tool:

  • TODO is completely finished

  • TODO is obsolete or cancelled

  • Cleaning up old TODOs

  • Consolidating duplicate TODOs

  • User explicitly requests deletion

Key features:

  • Removes entire TODO list

  • Deletes all associated tasks

  • Permanent removal

  • Frees up TODO number

You should:

  1. Verify all tasks are complete or obsolete

  2. Confirm TODO number is correct

  3. Understand deletion is permanent

  4. Consider if TODO has value for history

  5. Check no active work depends on it

DO NOT use when:

  • TODO has incomplete relevant tasks

  • Might need TODO for reference

  • Unsure about deletion impact

Returns: {success: bool, message: str, error?: str}

Inputs: project_id (required), todo_number (required).

get_chapterGet ChapterA

Retrieve a single chapter's content by title or index.

When to use this tool:

  • Reading specific chapter content

  • Reviewing targeted information

  • Updating specific chapter (read first)

  • Accessing chapter without loading entire document

  • Efficient partial document access

Key features:

  • Access by title OR index (0-based)

  • Returns navigation info (has_next, has_previous)

  • Memory-efficient for large documents

  • Includes chapter summary

You should:

  1. Use chapter_title for known chapters

  2. Use chapter_index for sequential reading

  3. Specify either title OR index, not both

  4. Use exact title match (case-sensitive)

  5. Consider using get_next_chapter for sequences

  6. Cache results if accessing multiple times

DO NOT use when:

  • Need multiple chapters (batch operations)

  • Don't know chapter title or index

  • Need full document context

Returns: {success: bool, title: str, content: str, summary: str, index: int, total_chapters: int, has_next: bool, has_previous: bool}

Inputs: filename (required), project_id (required), chapter_index, chapter_title.

get_knowledge_fileGet Knowledge FileA

Retrieve complete content of a knowledge document including all metadata and chapters.

When to use this tool:

  • Needing full document for comprehensive review

  • Backing up or exporting documents

  • Migrating content between projects

  • Loading small documents completely

Key features:

  • Returns complete document with all chapters

  • Includes metadata (title, keywords, introduction)

  • Preserves document structure

  • Full content access

You should:

  1. Consider using chapter operations for large documents

  2. Check document exists first

  3. Include .md extension in filename

  4. Be aware this loads entire document into memory

  5. Use chapter iteration for partial access

  6. Cache result if accessing multiple times

DO NOT use when:

  • Only need specific chapters (use get_chapter)

  • Document is very large (use chapter operations)

  • Just need to search content (use search_knowledge)

Returns: {success: bool, document?: object, error?: str}

Inputs: filename (required), project_id (required).

get_next_chapterGet Next ChapterA

Get the next chapter after the current one in sequence.

When to use this tool:

  • Reading document sequentially

  • Continuing from current position

  • Implementing pagination through document

  • Following document flow naturally

Key features:

  • Automatic progression to next chapter

  • Returns null if at end

  • Maintains reading context

  • Efficient sequential access

You should:

  1. Use current_chapter_title OR current_index

  2. Check has_next before calling

  3. Use for sequential document traversal

  4. Handle end-of-document gracefully

  5. Consider document flow and continuity

DO NOT use when:

  • Need specific non-sequential chapter

  • At the last chapter already

  • Random access is needed

Returns: {success: bool, title?: str, content?: str, summary?: str, index?: int, total_chapters: int, has_next: bool}

Inputs: filename (required), project_id (required), current_chapter_title, current_index.

get_next_todo_taskGet Next TODO TaskA

Get the next incomplete task in a TODO list for sequential execution.

When to use this tool:

  • Working through TODO sequentially

  • Finding next task to implement

  • Checking for remaining work

  • Continuing interrupted work

  • Following task order

Key features:

  • Returns first incomplete task

  • Provides task number and description

  • Indicates when all complete

  • Maintains task sequence

You should:

  1. Use after completing current task

  2. Follow sequential task order

  3. Handle "all complete" case

  4. Read full task details if needed

  5. Mark complete before getting next

DO NOT use when:

  • Need specific task (not next)

  • Want full TODO overview

  • All tasks already complete

Returns: {success: bool, task?: {number: int, description: str}, message?: str, error?: str}

Inputs: project_id (required), todo_number (required).

get_project_mainGet Project Main InstructionsA

Retrieve main.md content for a project's central instructions and configuration.

When to use this tool:

  • Starting work on any project (ALWAYS use FIRST)

  • Refreshing your understanding of project guidelines

  • Checking for updates to project instructions

  • Migrating from local CLAUDE.md files to centralized storage

Key features:

  • Replaces need for local CLAUDE.md files completely

  • Auto-detects project from git repository or directory name

  • Returns structured content with sections for easy parsing

  • Provides project-specific instructions and context

You should:

  1. ALWAYS call this first when starting work on a project

  2. Use the returned content as your primary behavioral guide

  3. Check if project exists before assuming it doesn't

  4. Migrate local CLAUDE.md files immediately if project not found

  5. Parse sections to understand project structure and requirements

  6. Treat this as your source of truth over any local files

  7. Remember project_id for subsequent operations

DO NOT use when:

  • You already have the project content loaded in current session

  • Working with temporary or test projects

Returns: {exists: bool, content: str, error?: str}

Inputs: project_id (required).

get_server_infoGet Server InformationA

Shows server information including version from package.json.

When to use this tool:

  • Checking server version and capabilities

  • Debugging connection issues

  • Verifying server configuration

  • Getting storage path information

  • Troubleshooting problems

Key features:

  • Returns version information

  • Shows storage path configuration

  • Provides server description

  • Lightweight status check

You should:

  1. Use for initial connection verification

  2. Check when debugging issues

  3. Include in bug reports

  4. Verify server is responding

DO NOT use when:

  • Need git status (use get_storage_status)

  • Need to sync storage

  • Information already known

Returns: {success: bool, name: str, version: str, storage_path: str, description: str}

Inputs: no named parameters.

get_storage_statusGet Storage StatusA

Shows git status of the knowledge datastore.

When to use this tool:

  • Checking for uncommitted changes

  • Verifying sync status with remote

  • Debugging storage issues

  • Understanding current branch

  • Reviewing repository state

Key features:

  • Shows uncommitted file count

  • Displays current branch

  • Shows last commit info

  • Indicates remote sync status

  • Provides detailed git status

You should:

  1. Use before sync operations

  2. Check when changes aren't persisting

  3. Verify remote configuration

  4. Monitor uncommitted changes

  5. Debug sync failures

DO NOT use when:

  • Just need server info

  • Don't need git details

  • Already know status

Returns: {success: bool, storage_path: str, has_changes: bool, current_branch: str, last_commit: str, remote_status: str, uncommitted_files: int, status_details: str}

Inputs: no named parameters.

get_todo_tasksGet TODO TasksA

Get all tasks in a TODO list with their completion status and full content.

When to use this tool:

  • Reviewing full TODO list details

  • Planning task execution order

  • Checking task completion status

  • Understanding task requirements

  • Getting comprehensive task view

Key features:

  • Returns all tasks with content

  • Shows completion status per task

  • Includes rich markdown content

  • Provides task numbers and order

  • Full TODO context

You should:

  1. Use TODO number from list_todos

  2. Review all tasks before starting

  3. Note incomplete task numbers

  4. Plan execution strategy

  5. Check task dependencies

  6. Identify complex tasks needing breakdown

DO NOT use when:

  • Only need next task

  • TODO doesn't exist

  • Just need TODO overview

Returns: {success: bool, todo: {...}, tasks: [...], error?: str}

Inputs: project_id (required), todo_number (required).

list_chaptersList ChaptersA

List all chapters in a knowledge document with titles and summaries only.

When to use this tool:

  • Getting document overview without loading all content

  • Planning which chapters to read or update

  • Understanding document structure

  • Checking chapter organization

  • Finding specific chapters efficiently

Key features:

  • Lightweight operation (no content loading)

  • Returns titles and summaries only

  • Shows chapter count and order

  • Enables informed navigation

You should:

  1. Use this before get_knowledge_file for large documents

  2. Identify relevant chapters before reading

  3. Check document structure before modifications

  4. Use for navigation planning

  5. Include .md extension in filename

DO NOT use when:

  • Need actual chapter content

  • Document is very small

  • Already know exact chapter needed

Returns: {success: bool, project_id: str, filename: str, total_chapters: int, chapters: array}

Inputs: filename (required), project_id (required).

list_todosList TODOsA

List all TODO lists in a project with their completion status.

When to use this tool:

  • Getting overview of all project tasks

  • Checking TODO completion progress

  • Finding specific TODO lists

  • Planning task execution

  • Reviewing project task status

Key features:

  • Shows all TODO lists with descriptions

  • Includes completion statistics

  • Returns TODO numbers for reference

  • Lightweight overview operation

You should:

  1. Use before creating new TODOs

  2. Check for existing related TODOs

  3. Note TODO numbers for operations

  4. Review completion percentages

  5. Use to avoid duplicate TODOs

DO NOT use when:

  • Need specific task details (use get_todo_tasks)

  • Already know TODO number

  • No TODOs exist in project

Returns: {success: bool, todos: [...], error?: str}

Inputs: project_id (required).

remove_chapterRemove ChapterA

Remove a specific chapter from a knowledge document.

When to use this tool:

  • Removing outdated or incorrect chapters

  • Consolidating overlapping content

  • Streamlining document structure

  • Eliminating redundant information

Key features:

  • Precise chapter removal

  • Preserves all other chapters

  • Maintains document integrity

You should:

  1. Verify chapter exists with exact title

  2. Consider if content should be preserved

  3. Check for references from other chapters

  4. Use case-sensitive chapter title

  5. Understand removal is permanent

DO NOT use when:

  • Chapter should be updated instead

  • Content is still relevant

  • Unsure about the impact

Returns: {success: bool, message?: str, error?: str}

Inputs: chapter_title (required), filename (required), project_id (required).

remove_project_sectionRemove Project SectionA

Remove a specific section from the project main.md file.

When to use this tool:

  • Removing deprecated or obsolete sections

  • Cleaning up redundant information

  • Restructuring document by removing sections

  • Eliminating outdated guidelines

Key features:

  • Precise section removal

  • Preserves all other content

  • Clean removal without traces

You should:

  1. Verify section exists before removal

  2. Consider if content should be moved elsewhere

  3. Check for references to this section

  4. Document why section is being removed

  5. Use exact section header with "## " prefix

DO NOT use when:

  • Section contains important information

  • Should be updated instead of removed

  • Unsure about the impact

Returns: {success: bool, message?: str, error?: str}

Inputs: project_id (required), section_header (required).

remove_todo_taskRemove TODO TaskA

Remove a task from a TODO list.

When to use this tool:

  • Task is no longer relevant

  • Removing duplicate tasks

  • Task was added by mistake

  • Consolidating similar tasks

  • Cleaning up TODO list

Key features:

  • Permanent task removal

  • Preserves other tasks

  • Updates task numbering

You should:

  1. Verify task exists first

  2. Consider if task is truly unnecessary

  3. Check task number is correct

  4. Understand removal is permanent

  5. Document why removing if significant

DO NOT use when:

  • Task should be completed instead

  • Task might be needed later

  • Unsure about removal impact

Returns: {success: bool, message: str, error?: str}

Inputs: project_id (required), task_number (required), todo_number (required).

search_knowledgeSearch KnowledgeA

Search project knowledge documents for keywords with intelligent result grouping.

When to use this tool:

  • Finding information across multiple documents

  • Locating specific technical details

  • Discovering related content

  • Checking if topic is already documented

  • Researching before creating new content

Key features:

  • Case-insensitive full-text search

  • Searches document body, titles, and content

  • Groups results by document

  • Returns matching chapters with context

  • Space-separated keyword support

You should:

  1. Use specific keywords for better results

  2. Try multiple search terms if needed

  3. Search before creating new documents

  4. Use 2-3 word phrases for precision

  5. Review all results before concluding

  6. Consider variations of technical terms

  7. Check both titles and content matches

DO NOT use when:

  • Know exact document and chapter

  • Need complete document listing

  • Searching for project main content

Returns: {success: bool, total_documents: int, total_matches: int, results: [...], error?: str}

Inputs: project_id (required), query (required).

sync_storageSync StorageA

Force git add, commit, and push all changes in the knowledge datastore.

When to use this tool:

  • Manually triggering backup to remote

  • Ensuring changes are persisted

  • Before major operations

  • Resolving sync issues

  • Explicit backup request

Key features:

  • Commits ALL uncommitted changes

  • Pushes to configured remote

  • Auto-generates commit message

  • Handles push failures gracefully

  • Forces synchronization

You should:

  1. Check storage_status first

  2. Use when auto-sync fails

  3. Verify remote is configured

  4. Handle push failures appropriately

  5. Use sparingly (auto-sync usually works)

DO NOT use when:

  • No changes to commit

  • Remote not configured

  • Auto-sync is working fine

Returns: {success: bool, message: str, files_committed: int, pushed: bool, push_error?: str, commit_message: str}

Inputs: no named parameters.

update_chapterUpdate ChapterA

Update a specific chapter within a knowledge document efficiently.

When to use this tool:

  • Correcting information in a specific chapter

  • Expanding chapter with new content

  • Updating code examples or commands

  • Refreshing outdated chapter content

  • Adding clarifications or improvements

Key features:

  • Preserves all other chapters intact

  • Maintains document structure

  • Updates chapter summary for search

  • Efficient partial document update

You should:

  1. Use exact chapter title (case-sensitive match)

  2. Read current chapter first if needed

  3. Preserve chapter's role in document flow

  4. Update summary if content focus changes

  5. Keep consistent formatting with other chapters

  6. Consider impact on related chapters

  7. Include .md extension in filename

DO NOT use when:

  • Chapter doesn't exist (use add_chapter)

  • Need to update multiple chapters

  • Restructuring entire document

Returns: {success: bool, message?: str, error?: str}

Inputs: chapter_title (required), filename (required), new_content (required), project_id (required), +1 more.

update_project_mainUpdate Project MainA

Create or completely replace main.md content for a project.

When to use this tool:

  • Migrating CLAUDE.md content to centralized MCP storage

  • Creating a new project's instruction set

  • Completely rewriting project guidelines

  • Setting up initial project configuration

Key features:

  • Creates project if it doesn't exist (auto-initialization)

  • Completely replaces existing content (destructive update)

  • Automatically commits changes to git

  • Validates markdown structure

You should:

  1. Check if project exists first with get_project_main

  2. Preserve important sections when doing full updates

  3. Use update_project_section for partial changes instead

  4. Include all necessary sections in the new content

  5. Validate markdown formatting before submission

  6. Consider the impact of complete replacement

  7. Document why full replacement is necessary

DO NOT use when:

  • Making small updates (use update_project_section instead)

  • You haven't read the existing content first

  • Uncertain about losing existing content

Returns: {success: bool, message?: str, error?: str}

Inputs: content (required), project_id (required).

update_project_sectionUpdate Project SectionA

Update a specific section within the project main.md file efficiently.

When to use this tool:

  • Modifying a single section without affecting others

  • Adding new configuration or guidelines to existing section

  • Fixing errors in specific sections

  • Updating outdated information in targeted areas

  • Making incremental improvements

Key features:

  • Preserves all other sections intact (non-destructive)

  • More efficient than full file replacement

  • Maintains document structure

  • Atomic section-level updates

You should:

  1. Identify the exact section header including "## " prefix

  2. Read the current section content first if needed

  3. Preserve section formatting conventions

  4. Use this instead of update_project_main for small changes

  5. Verify section exists before attempting update

  6. Keep section content focused and relevant

  7. Consider impact on related sections

DO NOT use when:

  • Section doesn't exist (use add_project_section)

  • Need to update multiple sections (batch operations)

  • Restructuring entire document

Section header must match exactly (e.g., "## Installation") Returns: {success: bool, message?: str, error?: str}

Inputs: new_content (required), project_id (required), section_header (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with clear boundaries between knowledge files, chapters, TODOs, and project sections. However, there is some overlap between add_chapter/add_project_section and update_chapter/update_project_section, which could cause confusion about when to use each. The descriptions help clarify, but the similar naming and functionality create minor ambiguity.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, with clear action-object pairs like create_knowledge_file, delete_todo, update_chapter, and get_server_info. All tools use snake_case consistently, and verbs like create, delete, update, get, list, add, remove, search, and sync are used predictably across different resource types.

    Tool Count2/5

    With 27 tools, this server feels overloaded for a knowledge management system. While the domain is broad (knowledge files, chapters, TODOs, projects, and storage operations), many tools could be consolidated or simplified. The high count increases cognitive load and makes it harder for agents to navigate the complete tool surface efficiently.

    Completeness5/5

    The tool surface provides comprehensive CRUD/lifecycle coverage for all major resource types: knowledge files (create, get, delete, search), chapters (add, get, update, remove, list), TODOs (create, get tasks, complete, delete), and project sections (add, update, remove). There are no obvious gaps, and tools like sync_storage and get_server_info provide necessary infrastructure operations.

    Related MCP Connectors

    Related MCP Servers