Knowledge Shelf MCP Server

A personal knowledge management system for AI coding assistants, built as an MCP server. Store documentation, code patterns, templates, and workflows locally — AI pulls only what it needs, when it needs it.

The Problem

AI assistants forget everything between sessions. You explain the same patterns, paste the same boilerplate, re-describe the same internal APIs — over and over.

Steering files help, but they load everything into context upfront. For large knowledge bases (library docs, code templates, workflow guides), this wastes context budget and slows responses.

The Solution

knowledge-shelf gives AI on-demand access to your knowledge. AI searches, finds what's relevant, and loads only that — like a developer searching internal docs.

You: "Set up AG Grid testing for this project"

AI: [searches knowledge] → finds cucumber-boilerplate
    [reads manifest] → discovers ag-grid module + setup workflow
    [runs workflow] → scaffolds page objects, step definitions, config
    Done. Project ready.

What You Can Store

How It Works

~/.knowledge/                          ← Your knowledge lives here
├── cucumber-boilerplate/              ← Manifest-based unit (code + workflows)
│   ├── manifest.json
│   ├── pages/AgGridPage.java
│   ├── workflows/setup-project.json
│   └── references/ag-grid-guide.md
├── spring-patterns/                   ← Another unit
│   ├── manifest.json
│   └── ...
└── team-guides/                       ← Simple markdown docs
    ├── deployment.md
    └── coding-standards.md

AI accesses this through 7 MCP tools:

Quick Start

Initialize your knowledge directory

npx knowledge-shelf init

Add knowledge from a git repo

npx knowledge-shelf add https://github.com/your-team/shared-knowledge.git --all

Configure your AI Assistant

Add the configuration below to your MCP client's configuration file. Here are the paths for some popular tools:

• Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
• Cursor: .cursor/mcp.json (Workspace)
• Windsurf: ~/.windsurf/mcp.json
• Kiro: .kiro/settings/mcp.json
• Antigravity: ~/.gemini/config/mcp.json
• And other MCP-compatible clients...

{
  "mcpServers": {
    "knowledge": {
      "command": "npx",
      "args": ["-y", "knowledge-shelf"],
      "disabled": false,
      "autoApprove": [
        "list_docs",
        "search_docs",
        "get_doc",
        "get_doc_section",
        "get_resource",
        "get_manifest"
      ]
    }
  }
}

That's it. AI now has access to your knowledge.

Note: run_workflow is intentionally excluded from autoApprove because it has side effects (creates files, runs scripts). Add it only if you trust all installed knowledge workflows.

To use a custom knowledge path:

{
  "mcpServers": {
    "knowledge": {
      "command": "npx",
      "args": ["-y", "knowledge-shelf", "C:\\path\\to\\knowledge"],
      "disabled": false,
      "autoApprove": [
        "list_docs",
        "search_docs",
        "get_doc",
        "get_doc_section",
        "get_resource",
        "get_manifest"
      ]
    }
  }
}

Tip: You can set a global KNOWLEDGE_DIR environment variable (e.g., to ~/.kiro/knowledge/ or an absolute path) to persistently change the default directory for both CLI commands and MCP Server operations without passing paths or cờ (flags) manually.

Two Knowledge Formats

Manifest-based (for code, templates, workflows)

Best for reusable code patterns and automation. A folder with manifest.json:

{
  "name": "my-boilerplate",
  "version": "1.0.0",
  "type": "boilerplate",
  "description": "Page objects and step definitions for Angular testing",
  "tags": ["cucumber", "selenium", "angular"],
  "modules": { "base": { "files": ["pages/BasePage.java"], ... } },
  "workflows": { "setup": { "description": "Scaffold new project" } }
}

Standalone markdown (for documentation)

Best for guides, conventions, API docs. Just .md files with optional frontmatter:

---
description: "Internal REST API authentication patterns"
tags: auth, jwt, spring-security
aliases: auth-guide
---

# Authentication Guide

...

Knowledge Shelf CLI

Manage knowledge sources from git repositories — like npm for documentation.

Install globally to use the CLI directly without npx:

npm install -g knowledge-shelf

knowledge-shelf init                    # Initialize ~/.knowledge
knowledge-shelf add <url>               # Install from git repo
knowledge-shelf add <url> --all         # Install all units from monorepo
knowledge-shelf add <url> --path <dir>  # Install specific subfolder (sparse checkout)
knowledge-shelf search <keywords>       # Search installed knowledge
knowledge-shelf info <name>             # Show unit details
knowledge-shelf validate [name]         # Check structure integrity
knowledge-shelf list                    # Show installed sources
knowledge-shelf update [name]           # Pull latest from remotes
knowledge-shelf pin <name> [version]    # Lock version (skip updates)
knowledge-shelf unpin <name>            # Unlock
knowledge-shelf export <name>           # Package as zip for sharing
knowledge-shelf remove <name>           # Uninstall

See docs/cli-reference.md for full command documentation.

Sharing Knowledge

Organize a git repo and your team can install with one command:

# Single unit repo
knowledge-shelf add https://github.com/team/qa-boilerplate.git

# Monorepo with multiple units
knowledge-shelf add https://github.com/team/shared-knowledge.git --all

# Specific subfolder
knowledge-shelf add https://github.com/team/project.git --path knowledge/api-patterns --name api-patterns

See docs/publishing-knowledge.md for repo layout conventions.

Bundled Skill

Includes the knowledge-builder skill for AI-assisted knowledge creation. Install it directly using the CLI (defaults to the current directory if path is omitted):

knowledge-shelf install-skill [path-to-your-agent-skills]

The skill helps AI:

• Scaffold new knowledge units from scratch
• Generate reference docs from library source code
• Convert loose docs into manifest-based units
• Validate structure and fix issues

Documentation

Development

npm install
npm run build       # Compile TypeScript
npm run dev         # Run with tsx (hot reload)
npm test            # Run tests (vitest)
npm start           # Run compiled server

License

Apache-2.0