工艺MCP包装

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/)

一个模型上下文协议（MCP）服务器，它封装了多个Craft文档API，并使它们可供人工智能助手访问，如Perplexity AI、Claude Desktop、VS Code和Cursor。

注：这是一个开源项目。欢迎投稿！

📚 快速链接： 快速开始 | 贡献 | AWS部署 | 状态

概述

此MCP服务器提供了一个统一的界面，可以同时搜索和读取多个Craft文档中的内容。它跨配置的文档聚合结果，同时优雅地处理故障，使其成为查询分布式知识库的理想选择。

特性

5个MCP工具：

- list_documents -列出所有已配置的工艺文档 - search_all_notes -使用聚合在所有文档中搜索 - search_document -在特定文档中搜索 - read_document -读取整个文档结构 - read_block -按ID读取特定块

双重运输模式：

- 标准模式 -适用于本地AI助手（困惑本地，克劳德桌面） - SSE模式 -远程连接的HTTP/SSE传输

稳健的错误处理：

- 当单个API发生故障时，性能会下降 - 带有错误上下文的部分结果 - 使用Zod模式进行输入验证

易于配置：

- 基于JSON的文档配置 - 服务器设置的环境变量 - Craft公共共享链接不需要身份验证

安装

克隆存储库：

   git clone https://github.com/mattymil/craft-mcp-wrapper.git
   cd craft-mcp-wrapper

安装依赖项：

   npm install

配置您的工艺文档 （见下面的配置部分）

构建项目：

   npm run build

生产部署（macOS）

为了与MCP客户端稳定地进行生产使用，请部署到系统范围的位置：

# Build the project
npm run build

# Deploy to production location
sudo mkdir -p /usr/local/lib/craft-wrapper
sudo cp -r build config.json package.json node_modules /usr/local/lib/craft-wrapper/

然后配置您的MCP客户端以使用 /usr/local/lib/craft-wrapper/build/index.js 作为切入点。

优点：

稳定的路径不会随着项目更新而改变
将生产运行时与开发工作区分离
通过保留以前的版本轻松回滚

配置

文档配置(`config.json`)

编辑 config.json 添加您的Craft文档共享链接：

{
  "documents": [
    {
      "name": "My Notes",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_1/api/v1"
    },
    {
      "name": "Project Documentation",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_2/api/v1"
    }
  ]
}

要添加更多文档，请执行以下操作：

获取您文档的Craft共享链接
添加 /api/v1 到链接的末尾
添加具有友好名称和API终结点的新条目

环境变量(`.env`)

复制 .env.example 到 .env 并根据需要进行配置：

# Transport mode: "stdio" or "sse"
MCP_TRANSPORT=stdio

# SSE mode configuration (only used when MCP_TRANSPORT=sse)
PORT=3000
SSE_ENDPOINT=/sse

# Optional: API key for SSE authentication
# MCP_API_KEY=your-secret-key-here

# Performance tuning
# Maximum response size in bytes (default: 1048576 = 1MB)
# Larger values may cause stdio blocking with slow connections
MAX_RESPONSE_SIZE=1048576

性能配置：

MAX_RESPONSE_SIZE -JSON响应的最大大小（以字节为单位）（默认值：1MB）

- 大于此值的响应将被自动截断 - 大文档读取量增加，但要注意stdio阻塞 - 降低带宽以获得更快的性能

运行服务器

地方发展

标准模式（默认）

对于像Claude Desktop或Perplexity（本地）这样的本地AI助手：

npm start

这将在stdio模式下启动服务器，通过标准输入/输出进行通信。

SSE模式（HTTP服务器）

对于远程连接或测试：

npm run start:sse

或者明确地：

node build/index.js --sse

服务器将在端口3000上启动（可通过以下方式配置 PORT env变量），其中：

SSE端点： http://localhost:3000/sse
消息端点： http://localhost:3000/messages
健康检查： http://localhost:3000/health

本地Lambda测试

使用无服务器脱机在本地测试Lambda函数：

npm run offline

这将在上启动本地API网关仿真器 http://localhost:3000

发展模式

文件更改时自动重新加载：

# Stdio mode
npm run dev

# SSE mode
npm run dev:sse

AWS Lambda部署

使用API网关将服务器部署为AWS Lambda功能。

先决条件

AWS CLI已配置：

   aws configure

提供您的AWS访问密钥ID、秘密访问密钥和默认区域。

AWS凭据： 确保您有权限创建：

- 匿名函数 - API网关HTTP API - CloudWatch日志 - IAM角色

部署到AWS

部署到默认阶段（dev）：

npm run deploy

部署到特定阶段：

# Development
npm run deploy:dev

# Production
npm run deploy:prod

部署后，Serverless Framework将输出：

API网关端点URL
Lambda函数名称
CloudFormation堆栈名称

查看部署信息

npm run info

查看Lambda日志

# Tail logs in real-time
npm run logs

# Stage-specific logs
npm run logs:dev
npm run logs:prod

删除Lambda部署

# Remove default stage
npm run remove

# Remove specific stages
npm run remove:dev
npm run remove:prod

Lambda的环境变量

在中设置环境变量 serverless.yml 或通过命令行：

# Set API key for authentication
export MCP_API_KEY="your-secret-key"
npm run deploy

或编辑 serverless.yml:

provider:
  environment:
    MCP_API_KEY: ${env:MCP_API_KEY, 'default-key'}

Lambda配置

中的默认设置 serverless.yml:

运行时间： Node.js 20.x
内存： 512 MB
超时： 30秒
地区： 美国东部-1

修改这些 serverless.yml 根据需要。

API网关端点

部署后，您的Lambda在以下位置提供了一个REST API：

https://{api-id}.execute-api.{region}.amazonaws.com/

终点：

GET /health -健康检查

  curl https://{api-id}.execute-api.{region}.amazonaws.com/health

GET /tools -列出可用工具

  curl https://{api-id}.execute-api.{region}.amazonaws.com/tools

POST /tools/call -执行工具

  curl -X POST https://{api-id}.execute-api.{region}.amazonaws.com/tools/call \
    -H "Content-Type: application/json" \
    -d '{"name": "list_documents", "arguments": {}}'

注： Lambda部署使用简单的REST API，而不是完整的MCP协议。对于MCP协议支持（Perplexity要求），请使用本地stdio或SSE服务器。

成本估算

AWS Lambda：

免费层：每月1M请求+400000 GB秒计算
免费层之后：每100万次请求0.20美元+每秒0.0000166667美元

API网关：

免费等级：无
HTTP API：每百万次请求1.00美元

例子： 每月10000个请求，512MB，平均执行3秒：

Lambda：免费（在免费等级内）
API网关：0.01美元/月
总计：约0.01美元/月

Lambda限制

冷启动： 空闲期后的第一个请求可能较慢（1-2秒）
仅限REST API： Lambda提供REST API，而不是完整的MCP协议（对于MCP客户端使用本地服务器）
无stdio模式： Lambda（无服务器环境）不支持Stdio模式
无SSE/流媒体： Lambda REST API使用请求/响应，而不是服务器端事件
超时： 最长30秒（最多可配置15分钟）

连接AI助手

困惑AI

⚠️ 重要提示： 困惑需要通过stdio模式使用完整的MCP协议。使用本地服务器，而不是Lambda。

标准配置： 添加到困惑的MCP设置中：

{
  "mcpServers": {
    "craft-wrapper": {
      "command": "node",
      "args": ["/usr/local/lib/craft-wrapper/build/index.js"]
    }
  }
}

用于开发/自定义安装，替换为您的项目路径：

{
  "mcpServers": {
    "craft-wrapper": {
      "command": "node",
      "args": ["/path/to/your/craft-mcp-wrapper/build/index.js"]
    }
  }
}

注：这 MCP_TRANSPORT 环境变量默认为stdio，因此除非在您的 .env 文件。

克劳德桌面

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "craft-wrapper": {
      "command": "node",
      "args": ["/usr/local/lib/craft-wrapper/build/index.js"]
    }
  }
}

用于开发/自定义安装，替换为您的项目路径。

VS代码/光标

对于MCP兼容的扩展，请在工作区设置中配置服务器路径：

{
  "mcp.servers": {
    "craft-wrapper": {
      "command": "node",
      "args": ["/usr/local/lib/craft-wrapper/build/index.js"]
    }
  }
}

用于开发/自定义安装，替换为您的项目路径。

远程SSE连接

如果远程使用SSE模式（仅限本地服务器）：

Server URL: http://your-server:3000/sse

通过身份验证（如果 MCP_API_KEY 已设置）：

http://your-server:3000/sse?api_key=your-secret-key-here

Lambda REST API（用于自定义集成）

Lambda部署为不需要MCP协议的自定义集成提供了REST API：

基本URL: https://{api-id}.execute-api.{region}.amazonaws.com

示例-列出文档：

curl -X POST https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "list_documents", "arguments": {}}'

示例-搜索所有笔记：

curl -X POST https://YOUR-API-ID.execute-api.us-east-1.amazonaws.com/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_all_notes",
    "arguments": {
      "query": "leadership",
      "caseSensitive": false
    }
  }'

响应格式：

{
  "success": true,
  "result": {
    // Tool-specific result data
  }
}

工具文档

1. `list_documents`

列出所有已配置的工艺文档。

参数： 无

示例响应：

{
  "documents": [
    {
      "name": "My Notes",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_1/api/v1"
    },
    {
      "name": "Project Documentation",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_2/api/v1"
    }
  ],
  "count": 2
}

用例： 搜索前先发现可用文档。

2. `search_all_notes`

同时搜索所有已配置的文档。

参数：

query （字符串，必填）-搜索模式
caseSensitive （布尔值，可选）-区分大小写的搜索（默认值：false）

JSON-RPC请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_all_notes",
    "arguments": {
      "query": "leadership",
      "caseSensitive": false
    }
  },
  "id": 1
}

示例响应：

{
  "query": "leadership",
  "caseSensitive": false,
  "totalResults": 5,
  "documentsSearched": 2,
  "results": [
    {
      "documentName": "Notes",
      "results": [
        {
          "block": { "id": "...", "content": "..." },
          "documentName": "Notes"
        }
      ]
    },
    {
      "documentName": "Bonhoeffer Notes",
      "results": [...]
    }
  ]
}

用例： 在不知道哪个文档包含内容的情况下，在整个Craft知识库中查找内容。

3. `search_document`

在特定的工艺文档中搜索。

参数：

documentName （字符串，必填）-文档名称
query （字符串，必填）-搜索模式
caseSensitive （布尔值，可选）-区分大小写的搜索（默认值：false）

JSON-RPC请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_document",
    "arguments": {
      "documentName": "Notes",
      "query": "meeting notes",
      "caseSensitive": false
    }
  },
  "id": 2
}

用例： 当您知道哪个文档包含信息时，进行有针对性的搜索。

4. `read_document`

阅读Craft文档的整个结构。

参数：

documentName （字符串，必填）-文档名称
maxDepth （数字，可选）-块层次结构的最大深度

JSON-RPC请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_document",
    "arguments": {
      "documentName": "Notes",
      "maxDepth": 3
    }
  },
  "id": 3
}

用例： 检索完整的文档结构以进行分析或导出。

5. `read_block`

按ID读取特定块。

参数：

documentName （字符串，必填）-文档名称
blockId （string，必填）-块的ID

JSON-RPC请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_block",
    "arguments": {
      "documentName": "Notes",
      "blockId": "block-123-abc"
    }
  },
  "id": 4
}

用例： 当您从之前的搜索中获得块ID时，检索特定内容。

性能最佳实践

标准性能优化

此服务器针对与人工智能助手（如Perplexity）的快速stdio通信进行了优化：

压缩JSON： 禁用响应格式化（漂亮打印）以将有效负载大小减少约40%
响应大小限制： 大响应会自动截断，以防止stdio缓冲区阻塞
性能记录： 所有工具执行都会将时间和大小指标记录到stderr中进行监控

性能指标

检查stderr输出以获取性能数据：

[PERF] 2024-01-15T10:30:45.123Z search_all_notes 245ms size=15234bytes
[PERF] 2024-01-15T10:30:50.456Z read_document 1200ms size=524288bytes

最佳性能提示

使用特定搜索： 更喜欢 search_document 超过 search_all_notes 当你知道哪个文档包含数据时
极限深度： 使用 maxDepth 参数与 read_document 避免获取整个深层层次结构
监视器截断： 查看stderr [WARN] Response truncated 消息
调整大小限制： 增加 MAX_RESPONSE_SIZE 如果您经常看到截断警告
查询优化： 使用特定的搜索模式，而不是在所有文档中进行广泛的查询

当响应被截断时

如果响应超过 MAX_RESPONSE_SIZE，您将看到：

A. [WARN] stderr中包含原始大小和截断大小的消息
A. _metadata 响应中指示截断的字段
保留了截断数组/内容的顶级结构

解决：

增加 MAX_RESPONSE_SIZE 在你的 .env 文件
使用更具体的查询来减少结果集大小
使用 read_block 而不是 read_document 具体内容
减少 maxDepth 阅读文档时

测试

运行测试套件

npm run build
npm run test

测试套件验证：

所有5个工具均具有有效输入
处理无效输入时出错
配置加载
API响应结构

手动测试（SSE模式）

启动服务器：

npm run start:sse

测试健康终点：

curl http://localhost:3000/health

测试SSE连接：

curl http://localhost:3000/sse

列出可用工具：

curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

建筑

高级设计

┌─────────────────────┐
│   AI Assistant      │
│ (Perplexity/Claude) │
└──────────┬──────────┘
           │ MCP Protocol
           │ (stdio or SSE)
┌──────────┴──────────┐
│   MCP Server        │
│  (craft-wrapper)    │
│                     │
│  ┌───────────────┐  │
│  │ Tool Registry │  │
│  └───────┬───────┘  │
│          │          │
│  ┌───────┴───────┐  │
│  │ Craft API     │  │
│  │ Client        │  │
│  │ (axios)       │  │
│  └───────┬───────┘  │
└──────────┼──────────┘
           │
    ┌──────┴───────┐
    │              │
┌───┴────┐   ┌────┴──┐
│Craft   │   │Craft  │
│Doc 1   │   │Doc 2  │
└────────┘   └───────┘

聚合策略

当 search_all_notes 被称为：

为每个配置的文档创建并行承诺
使用 Promise.allSettled() 优雅地处理失败
使用文档名称上下文收集成功结果
包含失败请求的错误消息
返回汇总结果和汇总统计数据

错误处理

无效的文档名称： 返回可用文档列表错误
网络故障： 捕获并返回结构化错误
格式错误的响应： 包裹在错误对象中
部分故障： 仍然返回成功API的结果

故障排除

常见问题

“加载config.json失败”

确保 config.json 存在于项目根目录中
验证JSON语法是否有效
检查是否存在所有必填字段

“端口3000已在使用中”（SSE模式）

更改端口： PORT=3001 npm run start:sse
或更新 .env 文件

“未找到活动的SSE连接”

确保您已打开SSE端点(/sse)在发送消息之前
检查连接是否未关闭

网络错误/超时

验证工艺共享链接仍然有效
检查互联网连接
增加超时时间 craft-api.ts 如果需要（目前为30秒）

AI助手中未显示工具

重建项目： npm run build
重启AI助手
检查服务器日志是否有错误（stdio模式下的stderr）

表现缓慢，困惑/克劳德

检查stderr [PERF] 用于识别慢速操作的日志
较大的响应（>500KB）可能会导致延迟-请参阅下面的“响应截断”指南
验证 MAX_RESPONSE_SIZE 已适当设置（默认1MB）
使用更具体的搜索查询，而不是广泛的搜索

stderr中的“响应截断”警告

这意味着响应已超出 MAX_RESPONSE_SIZE 并被自动截断
检查 _metadata 截断细节响应中的字段
要修复：

- 增加 MAX_RESPONSE_SIZE 在 .env （例如。， MAX_RESPONSE_SIZE=2097152 2MB） - 使用更具体的查询来减小结果大小 - 使用 search_document 而不是 search_all_notes - 限制 maxDepth 通话时 read_document

注：设置 MAX_RESPONSE_SIZE 过高可能会导致stdio阻塞

已知限制

Lambda=仅限REST API： Lambda部署提供了一个REST API，而不是完整的MCP协议。对于MCP客户端（困惑、克劳德桌面），使用本地stdio/SSE服务器。
困惑需要本地服务器： Perplexity的MCP连接器需要stdio模式，该模式仅适用于本地服务器。
只读： 此MVP仅支持READ操作（搜索、获取）。写入操作（插入、更新、删除）未实现。
身份验证： Craft API必须是可公开访问的共享链接。尚不支持具有身份验证的私人文档。
速率限制： 没有内置的速率限制。如果提出许多请求，请考虑添加。

许可证

麻省理工学院

贡献

欢迎投稿！以下是您可以提供帮助的方式：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发环境设置

git clone https://github.com/mattymil/craft-mcp-wrapper.git
cd craft-mcp-wrapper
npm install
npm run build

运行测试

npm run test

支持

如果您遇到任何问题或有疑问：

打开一个问题
检查现有问题的解决方案
查看故障排除章节

______________________________________________________________________

内置：

模型上下文协议通过Anthropic
Craft.do API文件
TypeScript、Express、Axios、Zod

明星历史

如果你觉得这个项目有用，请考虑给它一个⭐ 在GitHub上！

Craft MCP Wrapper

快速接入

详细介绍

工艺MCP包装

概述

特性

安装

生产部署（macOS）

配置

文档配置(config.json)

环境变量(.env)

运行服务器

地方发展

标准模式（默认）

SSE模式（HTTP服务器）

本地Lambda测试

发展模式

AWS Lambda部署

先决条件

部署到AWS

查看部署信息

查看Lambda日志

删除Lambda部署

Lambda的环境变量

Lambda配置

API网关端点

成本估算

Lambda限制

连接AI助手

困惑AI

克劳德桌面

VS代码/光标

远程SSE连接

Lambda REST API（用于自定义集成）

工具文档

1. list_documents

2. search_all_notes

3. search_document

4. read_document

5. read_block

性能最佳实践

标准性能优化

性能指标

最佳性能提示

当响应被截断时

测试

运行测试套件

手动测试（SSE模式）

建筑

高级设计

聚合策略

错误处理

故障排除

常见问题

已知限制

许可证

贡献

开发环境设置

运行测试

支持

明星历史

相关项目

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

文档配置(`config.json`)

环境变量(`.env`)

1. `list_documents`

2. `search_all_notes`

3. `search_document`

4. `read_document`

5. `read_block`