KURA MCP客户端
模型上下文协议（MCP）客户端，使Claude Desktop能够与KURA Notes API交互。这个独立的客户端通过Claude的原生界面提供语义搜索、笔记创建、检索和管理功能。
特性
- 语义搜索：使用自然语言查询查找相关笔记
- 笔记创建：使用元数据（标题、标签、注释）创建文本注释
- 笔记检索：按ID获取特定笔记或列出最近的笔记
- 笔记管理：需要时删除注释
- 稳健的错误处理：清除API问题的错误消息
- 日志记录：详细记录到stderr进行调试
先决条件
- Node.js>=20.0.0
- Claude桌面应用程序
- KURA Notes API访问（需要API密钥）
安装
- 克隆或下载此存储库:
git clone
cd kura-mcp-client- 安装依赖项:
npm install- 构建项目:
npm run build这将：
- 将TypeScript编译为JavaScript - 生成 dist/index.js 文件 - 使输出文件可执行
配置
适用于克劳德桌面
将以下配置添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"kura-notes": {
"command": "node",
"args": ["/absolute/path/to/kura-mcp-client/dist/index.js"],
"env": {
"API_KEY": "your-kura-api-key-here",
"KURA_API_URL": "https://kura.tillmaessen.de"
}
}
}
}重要：替换 /absolute/path/to/kura-mcp-client 带有此项目目录的实际绝对路径。
环境变量
API_KEY（必需）：您的KURA Notes API身份验证密钥KURA_API_URL（可选）：KURA API基本URL（默认为https://kura.tillmaessen.de)
可用工具
1. kura_search
在KURA笔记中执行语义搜索。
参数:
query（字符串，必填）：搜索查询limit（数字，可选）：最大结果数（默认值：10）contentType（字符串，可选）：按内容类型筛选（例如“文本”）tags（字符串，可选）：以逗号分隔的标签进行筛选
示例:
Search my notes for "machine learning algorithms"回应：包含相关性得分和元数据的搜索结果数组。
2. kura_create
在KURA Notes中创建新的文本注释。
参数:
content（string，必填）：注释的主要内容title（字符串，可选）：注释的标题annotation（字符串，可选）：附加上下文或注释tags（字符串数组，可选）：用于对注释进行分类的标签
示例:
Create a note with the content "Today I learned about semantic search"
and tag it with "learning" and "ai"回应：创建了带有ID和元数据的注释。
3. kura_get
通过ID检索特定笔记。
参数:
id（string，必填）：钞票的唯一标识符
示例:
Get the note with ID "abc123"回应：完整的笔记内容和元数据，如果找不到，则出错。
4. kura_list_recent
列出20个最新的带有元数据的笔记（没有完整内容）。
参数：无
示例:
Show me my recent notes回应：包含元数据的最新笔记数组。
5. kura_delete
按ID删除笔记。此操作是永久性的。
参数:
id（string，必填）：要删除的注释的唯一标识符
示例:
Delete the note with ID "abc123"回应：成功确认或未找到错误。
使用示例
在Claude Desktop中配置后，您可以使用自然语言与KURA Notes进行交互：
- 搜索笔记:
- “在我的KURA笔记中搜索有关TypeScript的信息” - “查找标记为“项目想法”的笔记”
- 创建笔记:
- “创建一个笔记：'今天站立的会议笔记…'” - “把这个想法留给KURA：‘构建一个记笔记的MCP客户端’”
- 检索笔记:
- “获取笔记ID xyz789的完整内容” - “显示我最近的笔记”
- 删除笔记:
- “删除注释abc123”
故障排除
服务器未启动
症状：Claude Desktop显示连接错误
解决方案:
- 验证Node.js版本：
node --version（应大于等于20.0.0） - 检查中的绝对路径
claude_desktop_config.json是正确的 - 确保项目建成：
npm run build - 检查一下
dist/index.js存在并且可执行
API_KEY错误
症状：“错误：需要API_KEY环境变量”
解决方案:
- 验证
API_KEY设置在envClaude桌面配置的一部分 - 更改配置后重新启动Claude Desktop
- 检查配置文件中的拼写错误
身份验证错误
症状：“401未经授权”或“403禁止”错误
解决方案:
- 验证API密钥是否正确且处于活动状态
- 检查API密钥是否具有必要的权限
- 确保
Authorization标题格式正确
网络错误
症状：“获取失败”或连接超时错误
解决方案:
- 验证
KURA_API_URL正确且可访问 - 检查您的互联网连接
- 验证KURA API服务是否正在运行
查看日志
MCP客户端登录到stderr。要查看日志，请执行以下操作：
macOS/Linux:
- 关闭克劳德桌面
- 从终端运行：
/Applications/Claude.app/Contents/MacOS/Claude 2>&1 | grep "KURA MCP"视窗: 检查应用程序数据目录中的Claude Desktop日志。
发展
项目结构
kura-mcp-client/
├── README.md # This file
├── package.json # Project configuration and dependencies
├── tsconfig.json # TypeScript compiler configuration
├── .gitignore # Git ignore rules
├── src/
│ └── index.ts # Main MCP server implementation
└── dist/
└── index.js # Compiled JavaScript (after build)开发命令
# Install dependencies
npm install
# Build the project (compile TypeScript)
npm run build
# Run in development mode (with hot reload)
npm run dev
# Clean build artifacts
npm run clean
# Rebuild from scratch
npm run clean && npm run build手动运行测试
您可以手动测试MCP服务器：
# Set environment variables
export API_KEY="your-api-key"
export KURA_API_URL="https://kura.tillmaessen.de"
# Run the server (it will wait for MCP protocol messages on stdin)
node dist/index.js服务器通过JSON-RPC通过stdin/stdout进行通信，因此手动测试需要发送格式正确的MCP协议消息。
编码结构
主要实施 src/index.ts 包括：
- TypeScript接口：KURA API响应的类型定义
- 环境验证：检查所需的API_KEY
- 调用KuraAPI()：已通过身份验证的API请求的帮助程序函数
- MCP服务器设置：使用stdio传输初始化MCP服务器
- 工具定义：使用模式定义5个可用工具
- 请求处理程序:
- ListToolsRequestSchema：返回可用工具 - CallToolRequestSchema：执行带有错误处理的工具调用
添加新工具
要添加新工具，请执行以下操作：
- 将工具定义添加到
tools数组 - 在中添加新案例
CallToolRequestSchema处理器 - 实现API调用和响应处理
- 使用新的工具文档更新此README
api参考
客户端与以下KURA Notes API端点交互：
GET /api/search-语义搜索POST /api/capture-创建笔记GET /api/content/{id}-获取具体注释GET /api/content/recent-列出最近的笔记DELETE /api/content/{id}-删除注释
所有请求包括 Authorization: Bearer {API_KEY} 头球
技术细节
- 协议：通过stdio的模型上下文协议（MCP）
- 运输：通过标准输入/标准输出的JSON-RPC
- 语言：TypeScript编译为ES2022
- 运行时：Node.js>=20.0.0
- 软件开发工具包：@modelcontextprotocol/sdk v1.x
许可证
麻省理工学院
贡献
欢迎投稿！请确保：
- TypeScript代码遵循现有样式
- 所有工具都有适当的错误处理
- 文档已针对新功能进行了更新
- 代码编译时没有错误
支持
关于以下问题：
- 此MCP客户端：检查上面的故障排除部分
- KURA 笔记 API：联系您的KURA API管理员
- 克劳德桌面版：参观 Anthropic的支持
- MCP协议：参见 MCP文件