Jotty MCP Server

Jotty MCP服务器

MCP（模型上下文协议）服务器，用于将Claude Desktop连接到Jotty REST API，使语言模型能够与Jotty检查表和注释进行交互。

这个项目是用亚历山大的 mcp服务器启动器ts 模板，为MCP服务器开发提供了健壮和可扩展的基础。

特性

此服务器公开了11个工具来与您的Jotty数据交互：

• 检查表：

- AllChecklistsFetcher：从Jotty API检索与已验证用户关联的所有检查表。此工具为代理提供了访问MCP系统中用户完整清单的权限。 - ChecklistItemAdder：通过Jotty API将新项目添加到指定的检查表中。此工具允许代理在MCP系统中使用新任务或条目扩展现有检查表。 - ChecklistItemChecker：通过Jotty API将清单中的指定项目标记为完整。此工具允许代理更新MCP系统中检查表项目的状态。 - ChecklistItemUnchecker：通过Jotty API将检查表中的指定项目标记为不完整。此工具使代理能够管理MCP系统中检查表项目的状态。

• 笔记：

- AllNotesFetcher：从Jotty API检索与已验证用户关联的所有注释。该工具便于访问MCP系统中用户特定的笔记数据。 - NoteCreator：通过Jotty API为经过身份验证的用户创建新注释。此工具允许代理将新的文本信息添加到MCP系统中的用户集合中。 - NoteUpdater：通过Jotty API更新已验证用户的现有注释。 - NoteDeleter：通过Jotty API删除已验证用户的现有注释。

• 管理和数据管理：

- UserInfoFetcher：检索指定Jotty用户的详细信息。此管理工具提供了对MCP系统内用户配置文件的见解。 - CategoryFetcher：从Jotty API检索所有可用类别。此管理工具在MCP系统中提供了一个全面的分类选项列表。 - AccountSummaryFetcher：检索经过身份验证的Jotty帐户的摘要统计信息。此管理工具概述了MCP系统中的帐户活动和数据。 - DataExporter：以指定格式启动Jotty用户数据的完整导出。此管理工具可在MCP系统内实现全面的数据备份和迁移。 - ExportProgressMonitor：监视指定数据导出操作的进度。此管理工具为MCP系统内的数据导出任务提供实时状态更新。 - LinkIndexRebuilder：为特定用户重建内部链接索引。

• 系统：

- HealthChecker：检查Jotty API的运行状况。

安装

1.克隆存储库

git clone https://github.com/your-username/jotty-mcp-server.git
cd jotty-mcp-server

2.安装依赖项

npm install

配置

1. 环境变量：

创建一个 .env 通过复制将文件保存在项目根目录中 .env.example:

   cp .env.example .env

编辑 .env 提交并提供您的Jotty API详细信息：

   JOTTY_BASE_URL=http://localhost:1122
   JOTTY_API_KEY=ck_xxxxxxxxxxxxxxxx

1. 服务器API密钥（用于HTTP传输）：

如果使用HTTP传输，则必须设置 API_KEY 在你的 .env 文件。此密钥用于对MCP服务器的请求进行身份验证。

   API_KEY=your-secret-api-key

您可以使用UUID生成器或任何其他随机字符串生成器生成安全密钥。

1. CORS源（用于HTTP传输）：

如果您使用HTTP传输并从其他域访问服务器，请确保 CORS_ORIGIN 在你的 .env 文件（或 docker-compose.yml)配置正确。默认情况下，它设置为 * （允许所有来源）。

用法

运行服务器

• 开发模式（热重载）：

npm 运行开发模式 \\\`

• 生产模式（标准I/O-stdio）：

npm运行服务：stdio \\\`

• 生产模式（HTTP传输）：

npm运行服务：http \\\ HTTP服务器将侦听 http://localhost:3000/mcp` 默认情况下。

Docker部署

要使用Docker Compose构建和运行服务器：

1. 确保您的 .env 文件配置为 JOTTY_BASE_URL 和 JOTTY_API_KEY.
2. 从项目根目录运行：

docker构建 \\\ 服务器将通过端口上的HTTP进行访问 3000`.

使用Claude Desktop

1. 启动Jotty MCP服务器（在开发模式、生产stdio或生产HTTP中）。
2. 在Claude Desktop中，导航到 Settings > Model Context.
3. 点击“添加服务器”并进行配置：

- 对于stdio传输： 选择“标准I/O”并指向服务器可执行文件（例如。， node build/index.js 运行后 npm run build). - 对于HTTP传输： 选择“HTTP”并输入服务器URL（例如。， http://localhost:3000/mcp).您还需要添加一个用于身份验证的标头。点击“添加标题”，然后输入 Authorization 对于标题名称和 ApiKey your-secret-api-key 对于值（替换 your-secret-api-key 用你设置的钥匙 .env 文件）。

1. Jotty工具现在可以在您的Claude对话中使用。

测试

要运行所有单元和集成测试：

npm test

此命令执行位于以下位置的测试 tests/**/*.test.ts 和 src/__tests__/**/*.test.ts.

API 参考

有关所有可用工具及其参数的详细分类，请参阅 API毫米.

故障排除

• JOTTY_API_KEY not set 或无效： 确保您的 .env 文件已正确配置为有效 JOTTY_API_KEY 从...开始 ck_.
• Jotty API连接问题： 核实一下 JOTTY_BASE_URL 在你的 .env 正确，您的Jotty实例正在运行且可访问。
• 构建过程中的模块解析错误： 如果您遇到与模块导入相关的TypeScript错误，请确保 npm install 已成功运行，并且您的Node.js版本符合 engines 要求 package.json.
• CORS问题（HTTP传输）： 如果Claude Desktop（或其他客户端）在通过HTTP连接时遇到问题，请检查 CORS_ORIGIN 在环境变量中设置。

许可证

该项目根据MIT许可证获得许可。