工艺-MCP封装器

Name: 工艺-MCP封装器
Author: mattymil

作者：mattymil2 星标更新：2025-11-02

安装使用来源：spider==github.com

项目介绍

Craft MCP Wrapper

一个模型上下文协议（MCP）服务器，封装了多个Craft文档API，并使其能够被像Perplexity AI、Claude Desktop、VS Code和Cursor这样的AI助手访问。

注意： 这是一个开源项目。欢迎贡献！

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

概览

此MCP服务器提供了一个统一接口，用于同时搜索和读取多个Craft文档的内容。它在配置的文档之间聚合结果，优雅地处理失败情况，使其非常适合查询分布式知识库。

特性

5个MCP工具：
- list_documents - 列出所有配置的Craft文档
- search_all_notes - 跨所有文档进行聚合搜索
- search_document - 在特定文档中搜索
- read_document - 读取整个文档结构
- read_block - 根据ID读取特定区块
双传输模式：
- Stdio模式 - 适用于本地AI助手（Perplexity本地版、Claude Desktop）
- SSE模式 - HTTP/SSE传输用于远程连接
强大的错误处理：
- 当个别API失败时优雅降级
- 带有错误上下文的部分结果
- 使用Zod模式进行输入验证
简易配置：
- 基于JSON的文档配置
- 用于服务器设置的环境变量
- 对于Craft公共分享链接无需认证

安装

克隆仓库：

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

安装依赖：
```
npm install
```
配置你的Craft文档（参见下面的配置部分）
构建项目：
```
npm run build
```

生产部署（macOS）

为了与MCP客户端稳定生产使用，部署到系统全局位置：

# 构建项目
npm run build

# 部署到生产位置
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": "我的笔记",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_1/api/v1"
    },
    {
      "name": "项目文档",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_2/api/v1"
    }
  ]
}

要添加更多文档：

获取你的文档Craft分享链接
在链接末尾添加/api/v1
添加一个带有友好名称和API端点的新条目

环境变量（`.env`）

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

# 传输模式："stdio"或"sse"
MCP_TRANSPORT=stdio

# SSE模式配置（仅当MCP_TRANSPORT=sse时使用）
PORT=3000
SSE_ENDPOINT=/sse

# 可选：SSE身份验证的API密钥
# MCP_API_KEY=your-secret-key-here

# 性能调整
# 最大响应大小（默认：1048576 = 1MB）
# 较大的值可能会导致慢速连接下的stdio阻塞
MAX_RESPONSE_SIZE=1048576

性能配置：

MAX_RESPONSE_SIZE - JSON响应的最大字节数（默认：1MB）
- 超过此大小的响应将自动截断
- 增加以适应大型文档读取，但请注意stdio阻塞
- 减少以适应有限带宽下的更快性能

运行服务器

本地开发

Stdio模式（默认）

对于本地AI助手如Claude Desktop或Perplexity（本地版）：

npm start

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

SSE模式（HTTP服务器）

对于远程连接或测试：

npm run start:sse

或者明确指定：

node build/index.js --sse

服务器将在端口3000上启动（可通过PORT环境变量配置），具有以下端点：

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

本地Lambda测试

使用serverless-offline测试Lambda函数：

npm run offline

这将在http://localhost:3000启动一个本地API网关模拟器

开发模式

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

# Stdio模式
npm run dev

# SSE模式
npm run dev:sse

AWS Lambda部署

作为AWS Lambda函数部署服务器，使用API Gateway。

先决条件

配置AWS CLI：
```
aws configure
```
提供您的AWS访问密钥ID、秘密访问密钥和默认区域。
AWS凭证： 确保您有权创建：
- Lambda函数
- API Gateway HTTP API
- CloudWatch日志
- IAM角色

部署到AWS

部署到默认阶段（dev）：

npm run deploy

部署到特定阶段：

# 开发
npm run deploy:dev

# 生产
npm run deploy:prod

部署后，Serverless框架将输出：

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

查看部署信息

npm run info

查看Lambda日志

# 实时跟踪日志
npm run logs

# 阶段特定日志
npm run logs:dev
npm run logs:prod

移除Lambda部署

# 移除默认阶段
npm run remove

# 移除特定阶段
npm run remove:dev
npm run remove:prod

Lambda环境变量

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

# 设置API密钥用于认证
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秒
区域： us-east-1

根据需要修改这些设置。

API Gateway端点

部署后，您的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：

免费层级：每月1百万请求+ 400,000 GB-秒计算时间
超出免费层级：每1百万请求$0.20 + 每GB-秒$0.0000166667

API Gateway：

免费层级：无
HTTP API：每百万请求$1.00

示例： 每月10,000次请求，512MB，平均执行时间为3秒：

Lambda：免费（在免费层级内）
API Gateway：每月$0.01
总计：约$0.01/月

Lambda限制

冷启动： 空闲期后的首次请求可能较慢（1-2秒）
仅REST API： Lambda提供REST API，而非完整的MCP协议（使用本地服务器以支持MCP客户端）
不支持stdio模式： stdio模式在Lambda（无服务器环境）中不受支持
不支持SSE/流式传输： Lambda REST API使用请求/响应，而非服务器发送事件
超时： 最多30秒（可配置至15分钟）

连接AI助手

Perplexity AI

⚠️ 重要： Perplexity需要通过stdio模式的完整MCP协议。使用本地服务器，而非Lambda。

stdio配置： 添加到Perplexity的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文件中更改了默认设置，否则不需要指定。

Claude Desktop

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

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

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

VS Code / Cursor

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

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

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

远程SSE连接

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

服务器URL：http://your-server:3000/sse

带有认证（如果设置了MCP_API_KEY）：

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

Lambda REST API（自定义集成）

Lambda部署提供了一个REST API，用于不需要MCP协议的自定义集成：

基础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": "领导力",
      "caseSensitive": false
    }
  }'

响应格式：

{
  "success": true,
  "result": {
    // 工具特定的结果数据
  }
}

工具文档

1. `list_documents`

列出所有配置的Craft文档。

参数： 无

示例响应：

{
  "documents": [
    {
      "name": "我的笔记",
      "apiEndpoint": "https://connect.craft.do/links/YOUR_SHARE_LINK_1/api/v1"
    },
    {
      "name": "项目文档",
      "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": "领导力",
      "caseSensitive": false
    }
  },
  "id": 1
}

示例响应：

{
  "query": "领导力",
  "caseSensitive": false,
  "totalResults": 5,
  "documentsSearched": 2,
  "results": [
    {
      "documentName": "笔记",
      "results": [
        {
          "block": { "id": "...", "content": "..." },
          "documentName": "笔记"
        }
      ]
    },
    {
      "documentName": "Bonhoeffer笔记",
      "results": [...]
    }
  ]
}

用例： 在整个Craft知识库中查找内容，而无需知道哪个文档包含它。

3. `search_document`

在特定的Craft文档中搜索。

参数：

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

示例JSON-RPC请求：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_document",
    "arguments": {
      "documentName": "笔记",
      "query": "会议记录",
      "caseSensitive": false
    }
  },
  "id": 2
}

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

4. `read_document`

读取Craft文档的整个结构。

参数：

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

示例JSON-RPC请求：

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

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

5. `read_block`

根据ID读取特定的块。

参数：

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

示例JSON-RPC请求：

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

用例： 当你有一个从先前搜索获得的块ID时检索特定内容。

性能最佳实践

Stdio性能优化

此服务器针对与Perplexity等AI助手的快速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

最佳性能提示

使用具体搜索： 当你知道哪个文档包含数据时

工艺-MCP封装器

项目介绍

Craft MCP Wrapper

概览

特性

安装

生产部署（macOS）

配置

文档配置（config.json）

环境变量（.env）

运行服务器

本地开发

Stdio模式（默认）

SSE模式（HTTP服务器）

本地Lambda测试

开发模式

AWS Lambda部署

先决条件

部署到AWS

查看部署信息

查看Lambda日志

移除Lambda部署

Lambda环境变量

Lambda配置

API Gateway端点

成本估算

Lambda限制

连接AI助手

Perplexity AI

Claude Desktop

VS Code / Cursor

远程SSE连接

Lambda REST API（自定义集成）

工具文档

1. list_documents

2. search_all_notes

3. search_document

4. read_document

5. read_block

性能最佳实践

Stdio性能优化

性能指标

最佳性能提示

文档配置（`config.json`）

环境变量（`.env`）

1. `list_documents`

2. `search_all_notes`

3. `search_document`

4. `read_document`

5. `read_block`