MCPedia

A knowledge base server for AI agents via the Model Context Protocol (MCP). MCPedia stores, searches, and manages reusable knowledge entries -- skills, rules, patterns, guides, and references -- accessible to AI coding agents like Cursor, Codex, Claude, and others through the MCP standard.

Why MCPedia?

AI coding agents like Cursor, Claude, and Codex are powerful -- but they forget everything between sessions. MCPedia gives them persistent memory. You teach your agent something once (a coding pattern, a project convention, a debugging trick) and it remembers it forever.

What can you do with it?

• Save knowledge -- capture coding patterns, project rules, style guides, or anything your agent should know
• Search & retrieve -- your agent can search by keyword, filter by language/domain/project, or pull entries by context
• Share across agents -- the same knowledge base works with any MCP-compatible agent, so switching tools doesn't mean starting over
• Stay in control -- lock the database when you don't want agents making changes, unlock it when you do

Think of it as a personal wiki that your AI agents can read and write to, automatically.

Core Concepts

Entries

Entries are the primary knowledge units in MCPedia. Each entry has:

• A unique slug (URL-safe identifier, e.g. rust-error-handling)
• A title and optional description
• Content in Markdown format (up to 32 KB)
• Kind classification: skill, rule, context, pattern, reference, or guide
• Optional metadata: language, domain, project
• One or more tags for categorization
• Automatic version tracking and timestamps

Example:

{
  "slug": "rust-error-handling",
  "title": "Rust Error Handling",
  "description": "Idiomatic error handling patterns in Rust",
  "kind": "skill",
  "language": "rust",
  "domain": "",
  "project": "",
  "tags": ["rust", "errors", "result"],
  "version": 1,
  "content": "# Rust Error Handling\n\nUse `Result<T, E>` for recoverable errors..."
}

Tags

Tags provide flexible categorization across entries. Each tag tracks how many entries reference it, enabling discovery of related knowledge. Tags are managed automatically -- they are created when first used and cleaned up when no longer referenced.

Usage Statistics

MCPedia tracks usage statistics for each entry:

• Reads: incremented when an entry is fetched by slug or by context filters
• Searches: incremented when an entry appears in full-text search results
• Updates: incremented when an entry is modified

This enables agents to understand which knowledge is most frequently accessed.

Write Lock

MCPedia supports a database-level write lock to prevent AI agents from modifying the knowledge base when controlled access is desired. When locked, all write operations (create_entry, update_entry, delete_entry) are rejected. The lock is protected by a SHA-256 hashed token -- only the holder of the original token can unlock it.

API

MCPedia implements the MCP protocol version 2025-11-25 over HTTP using JSON-RPC 2.0. The server exposes a single endpoint at POST /mcp.

Tools

• search_entries

  • Full-text search across entries using SQLite FTS5 with snippet highlighting
  • Inputs:
    • query (string, required): Search query text
    • language (string, optional): Filter results by programming language (e.g. "rust", "python")
    • domain (string, optional): Filter results by domain (e.g. "backend", "security")
    • kind (string, optional): Filter results by kind ("skill", "rule", "context", "pattern", "reference", "guide")
    • tag (string, optional): Filter results by a specific tag
    • project (string, optional): Filter results by project slug
    • limit (integer, optional): Maximum number of results to return (default: 10, max: 50)
  • Returns matching entries with search snippets (content is not included in full)

• get_entry

  • Retrieve a single entry by its unique slug, including full content
  • Inputs:
    • slug (string, required): The unique slug identifier of the entry
  • Returns the complete entry with all metadata, tags, and full Markdown content
  • Increments the entry's read count in usage statistics

• get_entries_by_context

  • Retrieve entries matching contextual filters, with full content included
  • Inputs:
    • language (string, optional): Filter by programming language
    • domain (string, optional): Filter by domain
    • kind (string, optional): Filter by entry kind
    • tags (array of strings, optional): Filter by tags -- all specified tags must be present on the entry
    • project (string, optional): Filter by project slug
    • limit (integer, optional): Maximum number of results (default: 20, max: 50)
  • Returns full entries with content, suitable for injecting knowledge into agent context
  • Increments read counts for all returned entries

• list_entries

  • List all entries without content, with optional metadata filters
  • Inputs:
    • kind (string, optional): Filter by entry kind
    • language (string, optional): Filter by programming language
    • domain (string, optional): Filter by domain
    • project (string, optional): Filter by project slug
  • Returns entry metadata (slug, title, description, kind, language, domain, project) without content

• list_tags

  • List all tags in the knowledge base with their usage counts
  • No inputs required
  • Returns an array of tags, each with its name and count of associated entries

• create_entry

  • Create a new knowledge entry in the database
  • Inputs:
    • slug (string, required): Unique slug identifier (URL-safe)
    • title (string, required): Human-readable title
    • content (string, required): Markdown content (max 32 KB)
    • description (string, optional): Short summary of the entry
    • kind (string, optional): Entry kind -- one of "skill", "rule", "context", "pattern", "reference", "guide" (default: "skill")
    • language (string, optional): Programming language the entry relates to
    • domain (string, optional): Domain or area (e.g. "backend", "testing")
    • project (string, optional): Project slug this entry belongs to
    • tags (array of strings, optional): Tags for categorization
  • Returns the created entry with all fields populated
  • Blocked when the database write lock is active

• update_entry

  • Update an existing entry -- only provided fields are modified
  • Inputs:
    • slug (string, required): Slug of the entry to update
    • title (string, optional): New title
    • content (string, optional): New Markdown content (max 32 KB)
    • description (string, optional): New description
    • kind (string, optional): New kind classification
    • language (string, optional): New programming language
    • domain (string, optional): New domain
    • project (string, optional): New project slug
    • tags (array of strings, optional): New tags -- replaces all existing tags
  • Returns the updated entry; automatically increments version and updates timestamp
  • Blocked when the database write lock is active

• delete_entry

  • Permanently delete an entry by slug
  • Inputs:
    • slug (string, required): Slug of the entry to delete
  • Returns a confirmation message
  • Cascading deletion removes associated tags and usage statistics
  • Blocked when the database write lock is active

Resources

MCPedia exposes entries as MCP resources, allowing clients to browse and read knowledge entries using standard resource URIs. A built-in how-to-use entry is always available: if you have not added your own, the default content is served; creating one replaces it. The how-to-use resource is always first in resources/list and also available at mcpedia://how-to-use (see resources/templates/list).

• resources/list

  • Returns a paginated list of all entries as resources
  • Each resource includes:
    • uri: mcpedia://entries/<slug>
    • name: The entry slug
    • description: The entry description
    • mimeType: text/markdown
  • Pagination: 50 entries per page, cursor-based (base64-encoded offset)

• resources/read

  • Read a single entry's content by its resource URI
  • Input: uri (string) in the format mcpedia://entries/<slug>
  • Returns the entry's full Markdown content

• resources/templates/list

  • Returns URI templates:
    • mcpedia://how-to-use — Usage instructions for AI agents (read this first)
    • mcpedia://entries/{slug} — Access an entry by slug

Prompts

MCPedia provides three built-in prompts that help AI agents apply, review, and capture knowledge.

• apply-entry

  • Apply a knowledge entry's guidelines to the current task
  • Arguments:
    • slug (string, required): Slug of the entry to apply
  • Fetches the entry from the database and returns a prompt message with the entry's full content embedded, instructing the agent to follow the entry's guidelines

• review-with-entry

  • Review code against a knowledge entry's guidelines
  • Arguments:
    • slug (string, required): Slug of the entry to review against
  • Fetches the entry and returns a prompt message instructing the agent to evaluate code according to the entry's rules and best practices

• save-learnings

  • Extract and save reusable knowledge from the current task
  • No arguments required
  • Returns a prompt instructing the agent to identify reusable patterns, techniques, or rules from the current session and save them as new entries using the create_entry tool

Configuration

MCPedia is configured through environment variables and/or CLI flags. Flags take precedence over environment variables.

| Environment Variable | CLI Flag | Default | Description | |----------------------|-----------|---------------|-------------------------------------------------------| | MCPEDIA_DB | --db | mcpedia.db | Path to the SQLite database file | | MCPEDIA_ADDR | --addr | :8080 | HTTP server listen address | | MCPEDIA_TOKEN | --token | (empty) | Bearer token for authentication (empty = no auth) |

When a token is set, all HTTP requests must include an Authorization: Bearer <token> header. This protects the MCP endpoint from unauthorized access.

CLI Commands

MCPedia ships as a single binary with subcommands for database management, server operation, and entry management.

mcpedia <command> [flags]

Commands:
  init      Create and initialize the database
  serve     Start the MCP HTTP server
  add       Add a new knowledge entry
  edit      Edit an existing entry
  list      List entries with optional filters
  lock      Lock the database (prevent AI writes)
  unlock    Unlock the database
  export    Export all entries as Markdown files
  import    Import a single entry from an export-format Markdown file

mcpedia init

Creates and initializes the SQLite database with the required schema.

mcpedia init --db ./mcpedia.db

mcpedia serve

Starts the MCP HTTP server, ready to accept JSON-RPC 2.0 requests from MCP clients.

mcpedia serve --db ./mcpedia.db --addr :8080 --token my-secret-token

mcpedia add

Adds a new knowledge entry. Content is read from a file.

mcpedia add \
  --slug rust-error-handling \
  --title "Rust Error Handling" \
  --description "Idiomatic error handling patterns in Rust" \
  --file content.md \
  --kind skill \
  --language rust \
  --tags rust,errors,result

To customize the usage guide, add your own how-to-use entry—it replaces the built-in default. A reference implementation is in `h