Uses git remote URLs to automatically identify and organize projects, ensuring knowledge is stored and retrieved in a project-aware context
Stores knowledge in YAML-frontmatter markdown documents with chapter-based organization for structured information management
Uses YAML frontmatter for document metadata in knowledge files, supporting properties like title and keywords for better organization
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)
From Source
🛠️ Usage
MCP Client Configuration
Add to your MCP client configuration:
Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
:
Direct Execution
🤖 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:
⚠️ 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 foundFILE_ALREADY_EXISTS
: File/chapter already exists (use update instead)CHAPTER_NOT_FOUND
: Chapter title not found in documentSECTION_NOT_FOUND
: Section header not found in main.mdTODO_NOT_FOUND
: TODO list doesn't existINVALID_INPUT
: Parameters failed validationFILE_SYSTEM_ERROR
: File operation failedGIT_ERROR
: Git operation failed
Each error includes a traceId
for debugging.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
:
Generic MCP Configuration
For other MCP-compatible clients:
🔄 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
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
Git Remote Setup (Recommended)
Enable automatic cloud backup:
⚠️ 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 instructionsupdate_project_main(project_id, content)
- Update project instructionsupdate_project_section(project_id, section_header, new_content)
- Update specific sectionadd_project_section(project_id, section_header, content, position?, reference_header?)
- Add new sectionremove_project_section(project_id, section_header)
- Remove sectiondelete_project(project_id)
- Delete entire project
Knowledge Documents
create_knowledge_file(project_id, filename, title, introduction, keywords, chapters)
- Create structured documentget_knowledge_file(project_id, filename)
- Retrieve complete documentdelete_knowledge_file(project_id, filename)
- Delete documentupdate_chapter(project_id, filename, chapter_title, new_content, new_summary?)
- Update chapteradd_chapter(project_id, filename, chapter_title, content, position?, reference_chapter?)
- Add chapterremove_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 contentget_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 listscreate_todo(project_id, description, tasks?)
- Create new TODO listget_todo_tasks(project_id, todo_number)
- Get tasks in TODO listadd_todo_task(project_id, todo_number, title, content?)
- Add taskcomplete_todo_task(project_id, todo_number, task_number)
- Mark task completeget_next_todo_task(project_id, todo_number)
- Get next incomplete taskremove_todo_task(project_id, todo_number, task_number)
- Remove taskdelete_todo(project_id, todo_number)
- Delete entire TODO list
Server Operations
get_server_info()
- Get server version and configurationget_storage_status()
- Get Git repository statussync_storage()
- Force Git commit and sync
Resources
The server provides read-only resources for browsing:
knowledge://projects/{project_id}/main
- Project main instructionsknowledge://projects/{project_id}/files
- List of knowledge filesknowledge://projects/{project_id}/chapters/{filename}
- Chapter listings
🏗️ Architecture
Storage Structure
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:
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
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"
- Permission errors
- NPX cache issues
- Version conflicts
Debugging with Logs
Error Codes
The Knowledge MCP uses standardized error codes for debugging:
PROJECT_NOT_FOUND
- Project doesn't exist yet (callupdate_project_main
to create)DOCUMENT_NOT_FOUND
- Knowledge file not foundFILE_ALREADY_EXISTS
- File already exists (use update instead of create)SECTION_NOT_FOUND
- Section header not found in documentSECTION_ALREADY_EXISTS
- Section header already existsINVALID_INPUT
- Invalid parameters (check Zod validation errors)TODO_NOT_FOUND
- TODO list doesn't existTODO_TASK_NOT_FOUND
- Task not found in TODO listFILE_SYSTEM_ERROR
- File operation failedGIT_ERROR
- Git operation failed
Each error includes a unique traceId
for debugging. Search logs using: grep "traceId" ~/.knowledge-mcp/activity.log
Verifying Installation
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
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.
- 🚀 Features
- 📦 Installation
- 🛠️ Usage
- 🤖 AI Assistant Configuration
- ⚠️ IMPORTANT CONSTRAINTS
- 🔍 ERROR CODES
- For global scope (all projects) - ensures latest version is always used
- For current project only
- For development (using local build)
- Remove and re-add to ensure latest version
- 1. Create repository on GitHub/GitLab
- 2. Configure remote
- 3. Set up authentication (SSH recommended)
- Run all tests
- Run specific test suite
- Generate HTML test report
- Install dependencies
- Start development server with auto-reload
- Build for production
- Run type checking
- Run linter
- Format code
- Run all quality checks
- View MCP logs (location varies by client)
- For Claude Code:
- View activity logs with trace IDs
- Check Git repository status
- Check if Knowledge MCP is properly configured
- Test basic functionality (if using Claude Code)
- Should return server information
- Verify storage directory
Related MCP Servers
- -securityAlicense-qualityProvides knowledge graph functionality for managing entities, relations, and observations in memory with strict validation rules to maintain data consistency.Last updated -16PythonMIT License
- AsecurityFlicenseAqualityProvides tools for managing project knowledge graphs, enabling structured representation of projects, tasks, milestones, resources, and team members.Last updated -67TypeScript
- AsecurityFlicenseAqualityProvides tools for managing student knowledge graphs, enabling structured representation of courses, assignments, exams, concepts, and study resources.Last updated -6TypeScript
- AsecurityFlicenseAqualityAn 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 -52197TypeScript