Openproject MCP AI Integration

状态：正在进行中（WIP）。在工具表面和集成故事稳定的同时，欢迎做出贡献。

OpenProject MCP服务器

一种模型上下文协议（MCP）服务器，为AI助手提供高保真访问 打开项目 API v3。该服务器公开了用于项目发现、工作包协作、时间跟踪、附件、维基内容和用户解析的精选工具，所有这些都是通过针对LLM工作流优化的快速异步Python堆栈实现的。

目录

• 概述
• 建筑一瞥
• 工具目录
• 仓库的规划
• 快速入门
• 配置
• 运行服务器
• 与MCP客户合作
• 测试与质量
• 故障排除
• 已知限制和路线图
• 贡献
• 许可证

概述

• 专为MCP设计： 船与a FastMCP 可以放入Claude Desktop、Cursor、modelcontextclient或任何其他MCP主机中的实现。
• 异步和弹性： 用途 httpx 具有请求重试、指数回退、超时调优和经过净化的错误处理。
• 丰富的刀具表面： LLM可以对工作包进行评论、跨内容搜索、管理附件、解析用户、记录时间和查询wiki页面。
• 类型合同： Pydantic模型验证每个工具输入，以保护OpenProject API免受错误提示的影响。
• Pyproject专用工具： uv 驱动依赖关系管理，确保可重复的环境和快速的安装时间。

建筑一瞥

工具目录

每个工具都通过MCP协议公开——LLM完全按照这里的定义调用它们。

系统

• system_ping：快速准备检查（退货 {"ok": true})让MCP客户端验证连接。

工作包(src/openproject_mcp/tools/work_packages.py)

• add_comment：发布带有可选观察者通知的Markdown评论。
• search_content：搜索工作包和/或项目，可选择捕获附件匹配项。
• append_work_package_description：在处理乐观锁定时，将Markdown附加到现有描述中。
• get_work_package_statuses：列出经过身份验证的用户可用的所有状态。
• get_work_package_types：列出全局或项目范围内的每种类型。
• resolve_status：将人员身份名称转换为ID/消歧有效载荷。
• resolve_type：解析项目中的类型名称，包括当类型存在但在那里被禁用时的回退。

附件(src/openproject_mcp/tools/attachments.py)

• attach_file_to_wp：通过multipart/form数据将本地文件上传到工作包。
• list_attachments：枚举工作包上的附件。
• download_attachment：下载带有base64响应的二进制内容（可选地持久化到磁盘）以供内存使用。
• get_attachment_content：使用HTTP范围请求获取元数据和预览切片以节省带宽。

项目(src/openproject_mcp/tools/projects.py)

• get_project_memberships：使用分页和多页跟踪模式获取项目成员/角色映射。
• resolve_project：使用消歧提示解析名称/标识符，以便LLM可以选择正确的项目。

查询(src/openproject_mcp/tools/queries.py)

• list_queries：列出已保存的查询（全局或项目范围）。
• run_query：执行已保存的查询并支持提示时间过滤器覆盖。

时间条目(src/openproject_mcp/tools/time_entries.py)

• list_time_entries：使用本机OpenProject运算符按项目、工作包、用户和日期跨度进行筛选。
• log_time：将十进制小时转换为ISO-8601持续时间，并创建时间条目（包括可选的用户、活动和时间戳）。

用户(src/openproject_mcp/tools/users.py)

• resolve_user：按名称搜索活动主体。
• get_user_by_id：检索具有完整元数据的单个用户。

Wiki(src/openproject_mcp/tools/wiki.py)

• get_wiki_page：检索wiki元数据、版本和交叉链接。
• attach_file_to_wiki：将文件上传到wiki页面。
• list_wiki_page_attachments：在wiki页面上列出附件。

仓库的规划

├── src/openproject_mcp
│   ├── main.py            # CLI entry point (stdio server)
│   ├── server.py          # FastMCP factory + tool registration
│   ├── config.py          # Pydantic settings (env-driven)
│   ├── client.py          # Resilient httpx/OpenProject client
│   ├── errors.py          # Domain-specific exceptions and sanitisation
│   ├── utils/logging.py   # Log configuration helper
│   └── tools/             # Tool families grouped by domain
├── tests/                 # Async pytest suite and smoke tests
├── pyproject.toml         # uv/PEP 621 metadata + tooling config
├── uv.lock                # Locked dependency graph
├── requirements.txt       # Convenience export (mirrors pyproject deps)
└── env_example.txt        # Template for `.env`

快速入门

1. 安装必备组件

- Python 3.10+ - uv 用于快速安装(curl -LsSf https://astral.sh/uv/install.sh | sh) - 访问OpenProject实例和个人API令牌

1. 克隆存储库

   git clone https://github.com/your-org/openproject-mcp-ai-integration.git
   cd openproject-mcp-ai-integration

1. 安装依赖项

   uv sync  # creates .venv and installs runtime + dev deps

1. 配置环境

   cp env_example.txt .env
   # edit .env with your OpenProject URL + API token

1. 运行烟雾测试

   uv run python -m openproject_mcp.main  # prints nothing and blocks while serving stdio

停止 Ctrl+C 一旦您确认服务器启动时没有配置错误。

配置

openproject_mcp.config.Settings 使用以下环境变量（由于Pydantic，不区分大小写）。将它们分配到 .env 或通过您的MCP客户端配置。

其他按键 env_example.txt (OPENPROJECT_PROXY, TEST_CONNECTION_ON_STARTUP)是未来增强的占位符，目前被忽略。

运行服务器

该项目公开了一个名为的控制台脚本 openproj-mcp （配置于 pyproject.toml).运行它 uv 以确保通过项目虚拟环境解决依赖关系：

uv run openproj-mcp

• 该过程根据MCP规范通过stdio进行阻塞和通信。
• 使用 LOG_LEVEL=DEBUG 在调试期间显示HTTP请求/响应。
• 健康检查通过 system_ping 在调用其他工具之前，请先从MCP客户端调用。

与MCP客户合作

克劳德桌面（macOS和Windows）

向添加条目 claude_desktop_config.json:

{
  "mcpServers": {
    "openproject": {
      "command": "uv",
      "args": ["run", "openproj-mcp"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "sk_...",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

重新启动Claude Desktop并确认服务器出现在MCP工具列表中。其他MCP主机（游标、继续等）遵循相同的模式：指向 uv run openproj-mcp 并通过其配置UI提供环境。

测试与质量

该仓库包括异步优先测试和静态分析挂钩。

有用的医生住在 tests/TESTING_CHECKLIST.md （例如，以下清单 add_comment).

故障排除

集 LOG_LEVEL=DEBUG 以跟踪HTTP调用。服务器静音嘈杂 httpx 在更高的日志级别运行时记录日志。

已知限制和路线图

• 代理配置和启动连接测试被打断 .env_example 但未实施。
• 时间输入活动必须通过ID引用（例如，勾选OpenProject→ *行政→ 时间跟踪*).计划使用专用查找工具。
• 目前还没有高层权限检查；如果您收到403个错误，请使用OpenProject的UI确认权限。
• 今天只提供stdio运输。套接字或HTTP传输需要额外的粘合 FastMCP.
• 工具表面侧重于在中测试的读/写操作 tests/.如果您需要新的API覆盖范围（例如版本、关系），欢迎PR。

贡献

1. 分叉并克隆仓库。
2. 创建要素分支： git checkout -b feature/.
3. 跑 uv run ruff check, uv run black, uv run mypy，以及 uv run pytest 在承诺之前。
4. 提交一份PR，描述动机、进行的测试和任何OpenProject先决条件。

请避免泄露秘密--.env 被忽视，以及 errors.py 从异常文本中清除敏感标记。

学分和起源

这个代码库最初是从 openproject-mcp-server 项目by 一切 （麻省理工学院许可）。在奥列克桑德·波梅顿的领导下 自那以后，它被大量重构为一个独特的实现 具有不同的架构、工具设置和功能范围，旨在 生产就绪的MCP服务器和产品组合参考。

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

致谢

• 灵感来自 模型上下文协议 社区工作。
• 与集成 OpenProject API v3.