kitbag-mcp

Kitbag MCP 是一个集成了精选 50 多种高价值实用工具的开源模型上下文协议服务，涵盖文档转换器、OCR 处理工具、网页抓取工具、数据格式化工具以及 AI 开发者实用工具等。

无需安装、配置并付费托管十几个单用途 MCP 服务，只需安装一次 Kitbag MCP，然后按需启用模块即可。它完全在你的机器上运行：托管费用为零、无需 API 密钥、无需设置服务器。

---

📖 目录

点击展开

• 🚀 快速开始
• ⚙️ 客户端设置
  • Claude Desktop
  • Cursor
  • Windsurf
• 🎛️ 配置
• 🗺️ 工具分类索引
• 📚 完整工具目录
  • 📄 PDF 工具
  • 🌐 网页抓取与网络
  • 📸 图像与 OCR 工具
  • 📊 数据转换
  • 💻 开发者实用工具
  • 🛠️ 实用工具
  • 🧠 AI 分块器
• 🏗️ 架构
• 🛠️ 本地开发与贡献
• ⚖️ 许可证

---

🚀 快速开始（零配置）

使用 npx 即可立即运行（需要 Node.js）：

npx kitbag-mcp

暴露特定模块（节省大模型上下文 Token）

为避免 AI Agent 被过多工具选项淹没，请仅启用所需的工具：

# Enable PDF and Web scraping modules only
npx kitbag-mcp --enabled-modules pdf,web

---

⚙️ 支持的客户端配置

1. Claude Desktop

将以下条目添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "kitbag-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kitbag-mcp",
        "--enabled-modules",
        "pdf,web,image,data,utility,ai"
      ]
    }
  }
}

2. Cursor

1. 前往 Settings → Beta Features → MCP。
2. 点击 + Add New MCP Server。
3. 配置：
   • Name：Kitbag MCP
   • Type：stdio
   • Command：npx -y kitbag-mcp --enabled-modules pdf,web,data,utility

3. Windsurf

将以下条目添加到你的 mcp_config.json：

{
  "mcpServers": {
    "kitbag-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kitbag-mcp"
      ],
      "env": {
        "KITBAG_ENABLED_MODULES": "pdf,web,data,utility"
      }
    }
  }
}

---

🎛️ 配置标志和环境变量

Kitbag MCP 可通过命令行标志、环境变量或 JSON 配置文件进行配置，你可以根据工作流选择合适的方式。

配置来源	使用示例
命令行标志	--enabled-modules pdf,web 或 --enabled-tools utility.qr_generate
环境变量	KITBAG_ENABLED_MODULES=pdf,web 或 KITBAG_ENABLED_TOOLS=utility.qr_generate
JSON 配置	当前工作目录中的 kitbag-config.json 文件，或通过 --config /path/to/config.json 指定

kitbag-config.json 架构：

{
  "enabledModules": ["pdf", "web", "image", "data", "utility", "ai", "developer"],
  "enabledTools": [],
  "defaultTimeoutMs": 30000,
  "maxPayloadSizeBytes": 52428800
}

---

🗺️ 工具类别索引

---

📚 完整工具目录

📄 PDF 工具（pdf.*）

高性能的本地 PDF 解析器和处理工具。

工具名称	描述	Agent 提示词示例
pdf.convert_to_text	从 PDF 文档中提取原始文本。	“从 reports/invoice.pdf 中提取文本”
pdf.convert_to_markdown	解析 PDF 并将其整理为简洁的 Markdown。	“将 guide.pdf 的布局转换为 Markdown”
pdf.extract_images	提取嵌入 PDF 中的原始图像资源。	“提取 slide_deck.pdf 中的所有图像”
pdf.extract_tables	提取 PDF 页面中的结构化表格数据。	“提取 financial_report.pdf 中的所有表格”
pdf.merge	按顺序合并多个 PDF 文件。	“将 doc1.pdf 和 doc2.pdf 合并为一个文件”
pdf.split	从 PDF 中拆分指定页码范围。	“给我 main_guide.pdf 的第 1 到第 3 页”

---

🌐 网页抓取与网络（web.*）

与原始网页文档交互并查询网络系统。

工具名称	描述	Agent 提示词示例
web.to_markdown	抓取网页、清除冗余内容，并转换为 Markdown。	“将 https://example.com/blog 上的文章转换为 Markdown”
web.extract_metadata	提取标题、描述、OG 标签和 JSON-LD 数据。	“获取 URL https://news.ycombinator.com 的元数据”
web.extract_links	抓取网页并列出内部和外部链接。	“查找维基百科 AI 页面上的所有外部链接”
web.rss_parser	将 RSS 或 Atom 源 XML URL 解析为 JSON。	“获取 https://github.blog/feed/ 上的最新源内容”
web.sitemap_generator	获取并解析 sitemap.xml URL，提取所有 URL。	“获取 google.com 站点地图中的所有 URL”
web.dns_lookup	执行 DNS 解析（A、AAAA、MX、TXT 等）。	“查询域名 gmail.com 的 MX 记录”
web.youtube_transcript	提取带时间戳的文本转录和字幕。	“获取 https://www.youtube.com/watch?v=dQw4w9 的转录”

---

📸 图像与 OCR 工具（image.*）

在本地处理图像并提取文本。

工具名称	描述	Agent 提示词示例
image.ocr	使用 Tesseract OCR 在本地从图像中提取文本。	“从 screenshot.png 中提取文本”
image.resize	调整图像尺寸（宽度和高度）。	“将 avatar.png 调整为 200x200 像素”
image.compress	使用自定义质量压缩图像文件大小。	“将 banner.jpg 压缩至 80% 质量”
image.convert_format	转换图像格式（PNG、JPEG、WebP 等）。	“将 logo.png 转换为 webp 格式”
image.exif_metadata	从图像文件中提取 EXIF 相机和位置信息。	“显示 photo.jpg 的 GPS 坐标和相机型号”

---

📊 数据转换（data.*）

快速离线转换标准数据格式。

工具名称	描述	Agent 提示词示例
data.csv_to_json	将 CSV 文件或原始文本转换为 JSON。	“解析 users.csv 并以 JSON 格式返回”
data.json_to_csv	将 JSON 对象数组转换为 CSV 输出。	“将这个用户数组转换为 CSV 表格”
data.xml_to_json	将 XML 文档转换为结构化 JSON 对象。	“将这段配置 XML 文本转换为 JSON”
data.json_to_xml	将 JSON 对象转换为简洁的 XML 输出。	“将这个 JSON 对象导出为 XML 标签格式”
data.yaml_to_json	将 YAML 文档转换为 JSON。	“将 Kubernetes 配置 yaml 转换为 JSON”
data.json_to_yaml	将 JSON 对象转换为简洁的 YAML 格式。	“将这个数据库 JSON 块格式化为 YAML”
data.deduplicate	根据指定键对 JSON 对象数组去重。	“根据 ID 删除这个用户对象列表中的重复项”
data.diff_arrays	比较两个 JSON 数组并列出差异。	“比较数组 A 和 B，并显示新增项和删除项”

---

💻 开发者实用工具（developer.*）

为开发者提供标准格式、验证和布局工具。

工具名称	描述	Agent 提示词示例
developer.json_formatter	使用自定义缩进格式化并美化 JSON 字符串。	“使用 4 个空格缩进美化此 JSON 字符串”
developer.jwt_decoder	解码 JWT 令牌，以读取载荷和标头声明。	“解码此 JWT 令牌：eyJhbGciOiJI...”
developer.sql_formatter	按多种数据库方言格式化 SQL 字符串。	“为 PostgreSQL 格式化这个杂乱的 select 查询”
developer.mermaid_generate	创建 Mermaid 图表（流程图、时序图等）。	“生成一个表示此用户流程的流程图”
developer.openapi_parser	解析并格式化 OpenAPI/Swagger 规范文件。	“列出此 openapi.yaml 的端点和请求架构”
developer.regex_tester	测试文本是否匹配正则表达式。	“测试此电子邮件正则表达式是否匹配 [email protected]”
developer.cron_parser	解析 Cron 表达式并列出即将到来的执行时间。	“告诉我 Cron 任务 '0 9 * * 1-5' 下次何时运行”
developer.diff_files	显示文本文件之间的行差异。	“显示 fileA.txt 和 fileB.txt 之间的差异”
developer.diff_json	显示 JSON 架构之间的差异。	“突出显示 config1.json 和 config2.json 之间的结构变化”
developer.code_detector	检测编程语言和语法结构。	“这段代码是用什么编程语言编写的？”
developer.markdown_lint	检查并验证 Markdown 文件的格式。	“查找 index.md 中的样式错误或行尾空格”

---

🛠️ 实用工具（utility.*）

系统、网络和密码学辅助功能。

工具名称	描述	Agent 提示词示例
utility.qr_generate	将二维码生成为文件或 base64 Data URL。	“创建一个指向 https://github.com 的二维码”
utility.qr_read	从文件或数据流中读取并解码二维码。	“code.png 中的二维码写了什么？”
utility.base64_encode	将字符串/文件转换为 base64 格式。	“将字符串 'Hello World' 编码为 Base64”
utility.base64_decode	将 base64 字符串解码为文本。	“解码 'SGVsbG8gV29ybGQ='”
utility.uuid_generate	生成安全的 UUID（v4/v1）或安全密码。	“生成一个长度为 16 的安全密码”
utility.file_hash	计算文本/数据的 md5、sha1 或 sha256 哈希值。	“计算此字符串的 sha256 哈希值”
utility.email_validate	验证电子邮件地址的语法并检查其 MX 记录。	“检查 [email protected] 是否有有效的 MX 记录”
utility.ssl_check	查询任意域名的证书到期日期和信息。	“检查 google.com 的 SSL 证书何时到期”
utility.unit_convert	转换物理单位或数据单位的数值。	“将 1024 兆字节转换为吉字节”
utility.url_parser	将 URL 拆分为协议、域名、参数等部分。	“将此搜索查询 URL 解析为各个组成部分”
utility.zip_create	将文件或文件夹压缩为单个 ZIP 存档。	“将 source/ 和 assets/ 压缩到 workspace.zip”
utility.zip_extract	将 ZIP 存档解压到目标文件夹。	“将 archive.zip 中的文件解压到 build_dir/”

---

🧠 AI 分块器（ai.*）

动态分割大型文本结构，以便导入。

工具名称	描述	Agent 提示词示例
ai.text_chunker	使用段落/句子/单词策略对长文本分块。	“将此文本文档分成 500 个字符大小的块，重叠 50 个字符”

---

🏗️ 工作原理

flowchart LR
    A[AI Agent / Client] -->|MCP Protocol| B(Kitbag MCP Server)
    B --> C{Enabled Modules}
    C --> D[📄 pdf.*]
    C --> E[🌐 web.*]
    C --> F[📸 image.*]
    C --> G[📊 data.*]
    C --> H[💻 developer.*]
    C --> I[🛠️ utility.*]
    C --> J[🧠 ai.*]
    D & E & F & G & H & I & J --> K[Local Execution<br/>No External API Calls]
    K --> A

Kitbag MCP 作为单个本地进程运行。你的 AI 客户端通过标准 MCP 协议与它通信，且只有你启用的模块会作为工具开放，从而降低令牌用量，让工作流保持快速且私密。

---

🛠️ 本地开发与贡献

每个工具都完全独立。只需在 src/tools/<category>/<tool_name>/ 中创建文件夹，即可添加新工具。

贡献要求

文件	用途
tool.ts	主要执行代码，导出一个 ToolDefinition。
README.md	工具文档及参数说明。
example.json	示例输入和预期输出。
tests.ts	使用模拟对象编写的独立单元测试，必要时使用模拟对象，以便立即运行。

命令指南

# Build compiler output
npm run build

# Run all 50 module tests
npm test

# Run real-life execution checks (makes live API and DNS requests)
npx tsx src/tests/run_real_life.ts

---

⚖️ 许可证

本项目采用 MIT 许可证 发布。更多信息请参阅 LICENSE。本项目完全开源，可免费用于个人或商业用途，也可根据需要进行修改。