Orgmode MCP

组织模式MCP服务器

用于处理组织模式文件和工作流的MCP（模型上下文协议）服务器。此服务器使Claude Desktop和其他兼容MCP的客户端能够与您的组织模式文件交互，解析其结构，并对其执行各种操作。

特性

• ✨ 基于TypeScript的MCP服务器实现
• 🔧 用于发现和访问组织文件的六个直观工具
• 📡 高级MCP客户端功能的资源和提示
• 🎯 已准备好与Claude Desktop集成
• 🛠️ 开发友好，支持热重新加载
• 📁 支持通配符的可配置组织模式文件路径

快速开始

先决条件

• Node.js 18或更高版本
• npm或纱线

安装

1. 克隆或下载此存储库

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 配置您的组织模式文件：

   cp config-example.json config.json

然后编辑 config.json 指定组织模式文件的路径：

   {
     "orgFiles": [
       "/path/to/your/org/files/*.org",
       "/path/to/specific-file.org",
       "~/Documents/notes/**/*.org"
     ]
   }

这 orgFiles 阵列支持：

- 绝对文件路径： /Users/username/notes/work.org - 通配符模式： /Users/username/notes/*.org - 递归模式： /Users/username/notes/**/*.org - 前缀匹配： /Users/username/notes/life*.org - 蒂尔德扩建： ~/Documents/notes/*.org

看 配置 有关更多详细信息，请参阅第节。

运行服务器

开发模式

npm run dev

生产模式

npm start

测试服务器

您可以通过运行服务器并通过stdio发送MCP消息来手动测试服务器：

npm run dev

然后发送JSON-RPC消息，如下所示：

{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

配置

服务器需要 config.json 项目根目录中的文件，用于指定要处理哪些组织模式文件。

设置：复制 config-example.json 到 config.json 并更新路径以指向您的组织模式文件：

cp config-example.json config.json

配置文件格式

{
  "orgFiles": [
    "/absolute/path/to/file.org",
    "/path/to/directory/*.org",
    "/path/with/wildcard/life*.org",
    "~/Documents/notes/*.org"
  ]
}

支持的路径模式

• 绝对路径: /Users/username/notes/work.org
• 通配符模式:

- *.org -目录中的所有.org文件 - **/*.org -所有.org文件都是递归的 - life*.org -以“life”开头的文件

• 多种模式：列出数组中的多个路径和模式

验证

当服务器启动时，它将：

• 验证配置文件结构
• 展开所有glob模式以查找匹配的文件
• 在以下情况下报告错误：

- 配置文件缺少JSON或JSON无效 - 这 orgFiles 数组为空或缺失 - 没有与指定模式匹配的文件

• 在以下情况下显示警告：

- 单个模式不匹配任何文件 - 模式扩展遇到错误

示例配置

配置简单：

{
  "orgFiles": ["/Users/martin/notes/work.org"]
}

多个带通配符的文件：

{
  "orgFiles": [
    "/Users/martin/Dropbox/orgmode/work.org",
    "/Users/martin/Dropbox/orgmode/life*.org",
    "/tmp/scratch.org"
  ]
}

递归模式：

{
  "orgFiles": ["/Users/martin/Documents/**/*.org"]
}

项目结构

src/
├── index.ts          # Main entry point
├── server.ts         # Server setup and configuration
├── config.ts         # Configuration loader and validator
├── handlers/         # Request handlers
│   ├── tools.ts      # Tool request handlers (6 org-mode tools)
│   ├── resources.ts  # Resource request handlers
│   └── prompts.ts    # Prompt request handlers
├── utils/            # Utility functions
│   └── orgParser.ts  # Org-mode file parsing utilities
└── types/            # TypeScript type definitions

可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm run start -运行已编译的服务器
• npm run dev -使用TypeScript运行并热重新加载
• npm run clean -清理构建工件
• npm test -运行测试
• npm run test:watch -在监视模式下运行测试
• npm run test:coverage -使用覆盖率报告运行测试

与Claude Desktop集成

将此配置添加到您的Claude Desktop配置文件中（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "orgmode-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/orgmode-mcp/dist/index.js"],
      "env": {
        "CONFIG_PATH": "/absolute/path/to/orgmode-mcp/config.json"
      }
    }
  }
}

替换 /absolute/path/to/orgmode-mcp 安装的实际路径。

重要：The CONFIG_PATH 环境变量必须指向您的绝对路径 config.json 文件。

添加配置后，重新启动Claude Desktop。服务器将把您的组织模式文件作为MCP资源公开，可以通过Claude访问。

看 docs/claude-integration.md 了解更多详细说明。

可用工具

服务器提供了六种工具来处理组织模式文件：

发现工具

• list_org_files -获取所有组织文件的元数据（文件名、路径、类别、标题、文件标签）
• list_categories -获取所有包含文件计数和相关文件标签的类别

内容检索工具

• get_all_org_files -将所有组织文件合并到一个文档中
• get_org_file -按文件名获取特定的组织文件
• get_category -获取一个类别中的所有文件
• get_category_with_tag -获取按文件标签筛选的类别中的文件

这些工具反映了现有的资源结构，提供了与更喜欢工具而不是资源的MCP客户端的兼容性。

发展

看 docs/development.md 有关使用新工具和资源扩展服务器的指南。

测试

该项目包括对所有模块的全面测试：

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

测试位于 tests/ 目录和封面：

• 配置加载和验证（tests/config.test.ts）
• 服务器初始化（tests/Server.test.ts）
• 请求处理程序（tests/handler.test.ts）
• 工具实现（tests/tools.test.ts）