KURA Notes MCP Client

KURA MCP客户端

模型上下文协议（MCP）客户端，使Claude Desktop能够与KURA Notes API交互。这个独立的客户端通过Claude的原生界面提供语义搜索、笔记创建、检索和管理功能。

特性

• 语义搜索：使用自然语言查询查找相关笔记
• 笔记创建：使用元数据（标题、标签、注释）创建文本注释
• 笔记检索：按ID获取特定笔记或列出最近的笔记
• 笔记管理：需要时删除注释
• 稳健的错误处理：清除API问题的错误消息
• 日志记录：详细记录到stderr进行调试

先决条件

• Node.js>=20.0.0
• Claude桌面应用程序
• KURA Notes API访问（需要API密钥）

安装

1. 克隆或下载此存储库:

   git clone 
   cd kura-mcp-client

1. 安装依赖项:

   npm install

1. 构建项目:

   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进行交互：

1. 搜索笔记:

- “在我的KURA笔记中搜索有关TypeScript的信息” - “查找标记为“项目想法”的笔记”

1. 创建笔记:

- “创建一个笔记：'今天站立的会议笔记…'” - “把这个想法留给KURA：‘构建一个记笔记的MCP客户端’”

1. 检索笔记:

- “获取笔记ID xyz789的完整内容” - “显示我最近的笔记”

1. 删除笔记:

- “删除注释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 设置在 env Claude桌面配置的一部分
• 更改配置后重新启动Claude Desktop
• 检查配置文件中的拼写错误

身份验证错误

症状：“401未经授权”或“403禁止”错误

解决方案:

• 验证API密钥是否正确且处于活动状态
• 检查API密钥是否具有必要的权限
• 确保 Authorization 标题格式正确

网络错误

症状：“获取失败”或连接超时错误

解决方案:

• 验证 KURA_API_URL 正确且可访问
• 检查您的互联网连接
• 验证KURA API服务是否正在运行

查看日志

MCP客户端登录到stderr。要查看日志，请执行以下操作：

macOS/Linux:

1. 关闭克劳德桌面
2. 从终端运行：

   /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：执行带有错误处理的工具调用

添加新工具

要添加新工具，请执行以下操作：

1. 将工具定义添加到 tools 数组
2. 在中添加新案例 CallToolRequestSchema 处理器
3. 实现API调用和响应处理
4. 使用新的工具文档更新此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文件