MCPedia
通过以下方式为AI代理提供知识库服务器 模型上下文协议 （MCP）。MCPedia存储、搜索和管理可重用的知识条目——技能、规则、模式、指南和参考——可供Cursor、Codex、Claude等AI编码代理通过MCP标准访问。
为什么选择MCPedia？
Cursor、Claude和Codex等AI编码代理功能强大，但它们在会话之间会忘记一切。MCPedia为他们提供 持久内存。你只教你的代理一次东西（编码模式、项目约定、调试技巧），它就会永远记住它。
你能用它做什么？
- 保存知识 --捕获编码模式、项目规则、风格指南或您的代理应该知道的任何内容
- 搜索和检索 --您的代理可以按关键字搜索，按语言/域/项目筛选，或按上下文提取条目
- 跨代理共享 --相同的知识库适用于任何兼容MCP的代理，因此切换工具并不意味着重新开始
- 保持控制 --当您不希望代理进行更改时锁定数据库，当您进行更改时解锁数据库
把它想象成一个个人维基，你的人工智能代理可以自动读写。
核心概念
条目
条目是MCPedia的主要知识单元。每个条目都有：
- 独特 鼻涕虫 （URL安全标识符，例如。
rust-error-handling) - A. 标题 可选 描述
- 内容 Markdown格式（最大32 KB）
- 亲切的 分类：
skill,rule,context,pattern,reference，或guide - 可选元数据： 语言, 领域, 项目
- 一个或多个 标签 用于分类
- 自动 版本 跟踪和 时间戳
例子：
{
"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` for recoverable errors..."
}标签
标签为条目提供了灵活的分类。每个标签跟踪有多少条目引用它，从而发现相关知识。标签是自动管理的——它们在首次使用时创建，在不再被引用时被清理。
使用统计
MCPedia跟踪每个条目的使用统计数据：
- 阅读：当通过slug或上下文过滤器获取条目时递增
- 搜索：当条目出现在全文搜索结果中时递增
- 更新：修改条目时递增
这使代理能够了解哪些知识最常被访问。
写入锁定
MCPedia支持数据库级写锁，以防止AI代理在需要受控访问时修改知识库。锁定时，所有写入操作(create_entry, update_entry, delete_entry)被拒绝。该锁由SHA-256哈希令牌保护，只有原始令牌的持有者才能解锁。
API
MCPedia实施MCP协议版本 2025-11-25 使用JSON-RPC 2.0通过HTTP。服务器在以下位置公开了一个端点 POST /mcp.
工具
search_entries
- 使用SQLite FTS5对条目进行全文搜索，并突出显示代码段 - 输入： - query （字符串，必填）：搜索查询文本 - language （字符串，可选）：按编程语言筛选结果（例如。 "rust", "python") - domain （字符串，可选）：按域筛选结果（例如。 "backend", "security") - kind （字符串，可选）：按类型筛选结果("skill", "rule", "context", "pattern", "reference", "guide") - tag （字符串，可选）：按特定标记筛选结果 - project （字符串，可选）：按项目段块过滤结果 - limit （整数，可选）：返回的最大结果数（默认值：10，最大值：50） - 返回带有搜索片段的匹配条目（内容不完整）
get_entry
- 按单个条目的唯一slug检索单个条目，包括完整内容 - 输入： - slug （string，必填）：条目的唯一slug标识符 - 返回包含所有元数据、标签和完整Markdown内容的完整条目 - 在使用统计中增加条目的读取计数
get_entries_by_context
- 检索与上下文过滤器匹配的条目，包括完整内容 - 输入： - language （字符串，可选）：按编程语言筛选 - domain （字符串，可选）：按域筛选 - kind （字符串，可选）：按条目类型筛选 - tags （字符串数组，可选）：按标签筛选——所有指定的标签都必须出现在条目上 - project （字符串，可选）：按项目段块过滤 - limit （整数，可选）：最大结果数（默认值：20，最大值：50） - 返回包含内容的完整条目，适合将知识注入代理上下文 - 递增所有返回条目的读取计数
list_entries
- 列出所有没有内容的条目，并使用可选的元数据过滤器 - 输入： - kind （字符串，可选）：按条目类型筛选 - language （字符串，可选）：按编程语言筛选 - domain （字符串，可选）：按域筛选 - project （字符串，可选）：按项目段块过滤 - 返回不带内容的条目元数据（段符、标题、描述、种类、语言、域、项目）
list_tags
- 列出知识库中的所有标签及其使用次数 - 无需输入 - 返回一个标签数组，每个标签都有 name 和 count 相关条目
create_entry
- 在数据库中创建新的知识条目 - 输入： - slug （字符串，必填）：唯一段塞标识符（URL安全） - title （字符串，必填）：人类可读的标题 - content （字符串，必填）：Markdown内容（最大32KB） - description （字符串，可选）：条目的简短摘要 - kind （string，可选）：条目类型--其中之一 "skill", "rule", "context", "pattern", "reference", "guide" （默认值： "skill") - language （字符串，可选）：条目所涉及的编程语言 - domain （字符串，可选）：域或区域（例如。 "backend", "testing") - project （string，可选）：此条目所属的项目段塞 - tags （字符串数组，可选）：分类标签 - 返回已创建的条目，并填充所有字段 - 当数据库写锁处于活动状态时被阻止
update_entry
- 更新现有条目——仅修改提供的字段 - 输入： - slug （string，必填）：要更新的条目的字符串 - title （字符串，可选）：新标题 - content （字符串，可选）：新Markdown内容（最大32KB） - description （字符串，可选）：新描述 - kind （字符串，可选）：新种类分类 - language （字符串，可选）：新的编程语言 - domain （字符串，可选）：新建域 - project （字符串，可选）：新项目段塞 - tags （字符串数组，可选）：新标签--替换所有现有标签 - 返回更新后的条目；自动递增版本并更新时间戳 - 当数据库写锁处于活动状态时被阻止
delete_entry
- 通过slug永久删除条目 - 输入： - slug （string，必填）：要删除的条目的字符串 - 返回确认消息 - 级联删除会删除相关标签和使用统计信息 - 当数据库写锁处于活动状态时被阻止
资源
MCPedia将条目作为MCP资源公开，允许客户端使用标准资源URI浏览和读取知识条目 how-to-use 条目始终可用：如果您没有添加自己的条目，则提供默认内容；创建一个替代它。如何使用资源始终是第一位的 resources/list 也可在 mcpedia://how-to-use （参见 resources/templates/list).
resources/list
- 返回所有条目作为资源的分页列表 - 每种资源包括： - uri: mcpedia://entries/ - name：入口塞 - description：条目描述 - mimeType: text/markdown - 分页：每页50个条目，基于光标（base64编码偏移）
resources/read
- 通过资源URI读取单个条目的内容 - 输入： uri （字符串）格式 mcpedia://entries/ - 返回条目的完整Markdown内容
resources/templates/list
- 返回URI模板： - mcpedia://how-to-use --AI代理的使用说明（请先阅读） - mcpedia://entries/{slug} --通过slug访问条目
提示
MCPedia提供了三个内置提示，帮助AI代理应用、审查和获取知识。
apply-entry
- 将知识条目的指南应用于当前任务 - 论据： - slug （string，必填）：申请条目的字符串 - 从数据库中获取条目，并返回一条嵌入条目完整内容的提示消息，指示代理遵循条目的指导方针
review-with-entry
- 根据知识条目的指导方针审查代码 - 论据： - slug （string，必填）：要审查的条目 - 获取条目并返回提示消息，指示代理根据条目的规则和最佳实践评估代码
save-learnings
- 从当前任务中提取并保存可重用的知识 - 无需任何论据 - 返回一个提示，指示代理从当前会话中识别可重用的模式、技术或规则，并使用 create_entry 工具
配置
MCPedia是通过环境变量和/或CLI标志配置的。标志优先于环境变量。
| 环境变量 | CLI标志 | 默认值 | 描述 |
|---|---|---|---|
MCPEDIA_DB | --db | mcpedia.db | SQLite数据库文件的路径 |
MCPEDIA_ADDR | --addr | :8080 | HTTP服务器侦听地址 |
MCPEDIA_TOKEN | --token | *（空）* | 用于身份验证的承载令牌（空=无身份验证） |
设置令牌后，所有HTTP请求都必须包含 Authorization: Bearer 头球这可以保护MCP端点免受未经授权的访问。
CLI命令
MCPedia以单个二进制文件的形式发布，其中包含用于数据库管理、服务器操作和条目管理的子命令。
mcpedia [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 filemcpedia init
使用所需的模式创建和初始化SQLite数据库。
mcpedia init --db ./mcpedia.dbmcpedia serve
启动MCP HTTP服务器，准备接受来自MCP客户端的JSON-RPC 2.0请求。
mcpedia serve --db ./mcpedia.db --addr :8080 --token my-secret-tokenmcpedia add
添加新的知识条目。内容是从文件中读取的。
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要自定义使用指南，请添加您自己的 how-to-use entry——它取代了内置的默认值。参考实现在 how-to-use.md 在项目根：
mcpedia add --slug how-to-use --title "How to Use MCPedia" \
--description "Instructions for AI agents: read this first" \
--file how-to-use.md --kind guide --tags mcpedia,usage,ai-agentsmcpedia edit
编辑现有条目。仅更新提供的字段。
mcpedia edit \
--slug rust-error-handling \
--title "Rust Error Handling (Updated)" \
--file updated-content.md \
--tags rust,errors,result,anyhowmcpedia list
列出具有可选筛选器的条目。
mcpedia list --language rust --kind skillmcpedia lock / mcpedia unlock
锁定数据库以防止AI代理创建、更新或删除条目。当您希望代理具有只读访问权限时非常有用。
mcpedia lock --db ./mcpedia.db --token my-lock-secret
mcpedia unlock --db ./mcpedia.db --token my-lock-secretmcpedia export
使用YAML frontmatter将所有条目导出为Markdown文件。
mcpedia export --db ./mcpedia.db --out ./backup每个条目都写在 .md:
---
title: "Rust Error Handling"
kind: skill
language: rust
domain: ""
project: ""
tags: [rust, errors, result]
description: "Idiomatic error handling patterns in Rust"
---
# Rust Error Handling
Use `Result` for recoverable errors...mcpedia import
从使用与相同格式的Markdown文件导入单个知识条目 mcpedia export （YAML frontmatter之间 --- 分隔符，然后是正文）。入口 鼻涕虫 取自文件名（例如。 rust-error-handling.md → slug rust-error-handling).如果带有该slug的条目已经存在，import会打印一个错误并退出；如果要替换现有条目，请先删除它。
mcpedia import --db ./mcpedia.db --file ./backup/rust-error-handling.md文件必须以开头 ---，包含所需的frontmatter密钥(title, kind, language, domain, project, tags; description 是可选的），并使用关闭 --- 在内容之前。未知密钥或无效格式会导致明显错误并中止。
种子数据（学习）
这 learnings/ 该目录包含Rust、Go和Python的每种语言种子Markdown文件（导出格式）。要将它们加载到mcpedia中：
make -C learnings build用以下命令覆盖二进制文件或数据库 mcpedia_exe 和 mcpedia_db （默认值： mcpedia 和 mcpedia.db).看 learnings/README.md 用于目录布局。
使用游标
将MCPedia添加为Cursor配置中的MCP服务器(.cursor/mcp.json):
二进制
{
"mcpServers": {
"mcpedia": {
"url": "http://localhost:8080/mcp",
"env": {
"MCPEDIA_TOKEN": "your-secret-token"
}
}
}
}然后启动服务器：
mcpedia serve --addr :8080 --token your-secret-token码头工人
{
"mcpServers": {
"mcpedia": {
"url": "http://localhost:8080/mcp"
}
}
}然后通过Docker运行：
docker run -p 8080:8080 \
-v $(pwd)/mcpedia.db:/mcpedia.db \
-e MCPEDIA_DB=/mcpedia.db \
-e MCPEDIA_TOKEN=your-secret-token \
ghcr.io/pouriya/mcpedia:latest serve使用Claude Desktop
将MCPedia添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"mcpedia": {
"url": "http://localhost:8080/mcp"
}
}
}使用VS代码
将配置添加到 .vscode/mcp.json 在您的工作区或用户级MCP配置中（命令面板> MCP: Open User Configuration):
{
"servers": {
"mcpedia": {
"url": "http://localhost:8080/mcp"
}
}
}安装
预构建二进制文件
从以下网址下载适用于您平台的最新版本 页面：
| 平台 | 二进制 |
|---|---|
| macOS（arm64） | mcpedia-*-darwin-arm64 |
| Linux（amd64） | mcpedia-*-linux-amd64 |
| Windows（amd64） | mcpedia-*-windows-amd64.exe |
码头工人
从GitHub容器注册表中提取：
docker pull ghcr.io/pouriya/mcpedia:latest使用持久数据库运行：
docker run -p 8080:8080 \
-v $(pwd)/mcpedia.db:/mcpedia.db \
-e MCPEDIA_DB=/mcpedia.db \
-e MCPEDIA_TOKEN=your-secret-token \
ghcr.io/pouriya/mcpedia:latest serve从源代码构建
需要Go 1.24+。
git clone https://github.com/pouriya/mcpedia.git
cd mcpedia
# Development build
make dev
# Or release build (stripped, cross-platform)
make release GOOS=linux GOARCH=amd64初始化并启动：
./mcpedia init
./mcpedia serve --addr :8080 --token my-secret-token在本地构建Docker镜像
make docker这创造了 mcpedia:latest 和 mcpedia: 图像。
建筑
┌─────────────────────────────────────────────┐
│ MCP Clients │
│ (Cursor, Codex, Claude, VS Code, etc.) │
└──────────────────┬──────────────────────────┘
│ HTTP POST /mcp
│ JSON-RPC 2.0
▼
┌─────────────────────────────────────────────┐
│ mcpedia binary │
│ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ CLI Commands │ │ MCP HTTP Server │ │
│ │ (init, add, │ │ (tools, │ │
│ │ edit, list, │ │ resources, │ │
│ │ lock, export)│ │ prompts) │ │
│ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ SQLite DB Layer │ │
│ │ (FTS5 search, tags, stats, lock) │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘项目结构
mcpedia/
├── cmd/mcpedia/
│ └── main.go # CLI entry point, all subcommands
├── internal/
│ ├── db/
│ │ ├── db.go # Database operations (CRUD, search, stats, lock)
│ │ └── schema.sql # SQLite schema (embedded via go:embed)
│ └── mcp/
│ └── mcp.go # MCP HTTP server (JSON-RPC 2.0, tools, resources, prompts)
├── test/
│ └── integration_test.go # Comprehensive integration tests
├── Makefile # Build automation
├── Dockerfile # Multi-stage Docker build
├── go.mod # Go module (pure Go SQLite, no CGO dependency at runtime)
└── go.sum关键设计决策
- 纯Go SQLite 通过
modernc.org/sqlite--无CGO运行时依赖性，单一静态二进制文件 - 单端点 (
POST /mcp)--标准MCP流式HTTP传输 - MCP协议
2025-11-25--完全符合工具、资源和提示 - FTS5全文搜索 --快速、排名搜索，突出显示代码片段
- 最小代码库 --3个Go源文件+1个SQL模式，没有不必要的抽象
- 会话管理 --基于UUID的会话
Mcp-Session-Id头球 - 供应商依赖关系 --无需网络访问即可复制构建
数据库模式
MCPedia使用SQLite和下表：
| 表 | 目的 |
|---|---|
entries | 带有符号、标题、内容、元数据的知识条目 |
tags | 唯一标签名称 |
entry_tags | 条目和标签之间的多对多关系 |
entry_stats | 使用统计（读取、搜索、更新） |
lock | 写入锁定状态（单行） |
entries_fts | 用于全文搜索的FTS5虚拟表 |
约束和特征：
CHECK(length(content) <= 32768)--32 KB内容大小限制- 条目上独特的slug约束
- 带的外键
CASCADE删除 - FTS5同步通过
AFTER INSERT/UPDATE/DELETE触发器 - 索引
language,domain,kind,project列
安全
- 承载令牌身份验证 --可选但推荐；保护MCP端点
- 写锁机制 --SHA-256哈希令牌可防止未经授权的修改
- 参数化SQL查询 --防止SQL注入
- 内容大小限制 --最大32KB防止滥用
- 会话验证 --初始化后的请求必须包含有效的
Mcp-Session-Id
发展
# Run tests with race detection
make test
# Run tests with coverage report
make test-cover
# Format check
make fmt
# Go vet
make vet
# Clean build artifacts
make clean许可证
此MCP服务器根据BSD 3条款许可证获得许可。版权所有（c）2022，Pouriya Jim Jahanbakhsh。有关更多详细信息，请参阅 许可证 项目存储库中的文件。