Teamwork.com

Teamwork MCP 服务

用于将 Teamwork.com 与大语言模型集成的 Model Context Protocol 服务

📌 您是 Teamwork.com 用户，现在想将 AI 工具连接到您的 Teamwork.com 站点吗？请直接查看 使用指南，了解令牌、启用 MCP 的方法，以及客户端配置示例。

📖 概述

此 MCP（Model Context Protocol）服务可实现大语言模型与 Teamwork.com 的无缝集成。它提供了标准化接口，让大模型能够与 Teamwork.com 项目交互，使 AI Agent 能够执行各种项目管理操作。

🤖 什么是 MCP？

Model Context Protocol（MCP）是一种开放协议，用于规范应用程序向大模型提供上下文的方式。此服务以大模型能够理解的方式描述 Teamwork.com 中的所有可用操作（工具），使 AI Agent 能够执行这些操作。

✨ 功能

• 多种传输模式：提供 HTTP 和 STDIO 接口，适用于不同的部署场景
• 安全认证：支持 Teamwork.com 的 Bearer 令牌和 OAuth2 集成
• 工具框架：可扩展的工具集架构，便于添加新功能
• 可用于生产环境：提供全面的日志记录、监控和可观测性
• 只读模式：可选择限制为只读操作，确保安全

请参阅自动生成的 工具参考，了解 Projects、Desk、Spaces 和 Chat 中提供的所有创建、读取和更新操作；也可以在 teamwork.github.io/mcp 浏览同一目录，其中提供了每个工具的说明和搜索筛选功能。

🚀 可用服务

此项目提供三种与 Teamwork.com MCP 服务交互的方式：

📡 HTTP 服务

适用于云部署和多客户端支持的生产级 HTTP 服务。

📖 HTTP 服务完整文档

快速开始：

TW_MCP_SERVER_ADDRESS=:8080 go run cmd/mcp-http/main.go

💬 STDIO 服务

面向桌面应用和开发环境的直接 STDIO 接口。

📖 STDIO 服务完整文档

快速开始：

TW_MCP_BEARER_TOKEN=your-token go run cmd/mcp-stdio/main.go

🛠️ HTTP CLI

用于测试和调试 MCP 服务功能的命令行工具。

📖 HTTP CLI 完整文档

快速开始：

go run cmd/mcp-http-cli/main.go -mcp-url=https://mcp.example.com list-tools

📋 先决条件

• Go 1.27 或更高版本
• 有效的 Teamwork.com API 凭据（Bearer 令牌或 OAuth2 配置）

🧪 开发与测试

运行测试

# Run all tests
go test ./...

# Run specific package tests
go test ./internal/twprojects/

MCP Inspector

如需调试，请使用 MCP Inspector 工具：

NODE_EXTRA_CA_CERTS=letsencrypt-stg-root-x1.pem npx @modelcontextprotocol/inspector node build/index.js

重要

注意：使用 Let's Encrypt 证书颁发机构进行 OAuth2 身份验证时，必须设置 NODE_EXTRA_CA_CERTS 环境变量。 请在此处下载证书。

🏗️ 架构

├── cmd/
│   ├── mcp-http/          # HTTP server implementation
│   ├── mcp-stdio/         # STDIO server implementation
│   ├── mcp-http-cli/      # CLI tool for testing via HTTP
│   ├── mcp-test/          # Walks tool handlers against a real site
│   ├── mcp-tokens/        # Token-cost report for the tool surface
│   └── docs-gen/          # Generates the tool reference (Markdown + GitHub Pages)
├── pkg/                   # Importable by other MCP servers built on this one
│   ├── auth/              # Authentication helpers (bearer & OAuth2 token handling)
│   ├── cli/               # -toolsets flag parsing
│   ├── config/            # Configuration management (env, flags), MCP server setup
│   ├── helpers/           # Shared utility functions (errors, link helpers, tool parsing)
│   ├── request/           # HTTP request primitives / Teamwork API wiring
│   ├── testutil/          # Product-neutral test mocks
│   ├── toolsets/          # Tool framework and registration logic
│   └── twctx/             # Per-request values derived from the bearer token
├── internal/              # This server's own tools, not importable elsewhere
│   ├── twprojects/        # Teamwork project/domain tools (tasks, tags, timers, etc.)
│   ├── twdesk/            # Teamwork Desk tools (tickets, customers, etc.)
│   ├── twspaces/          # Teamwork Spaces tools (spaces, pages, etc.)
│   └── twchat/            # Teamwork Chat tools (conversations, messages)
├── examples/              # Usage & integration examples (LangChain Node/Python)
├── docs/usage/            # End-user setup & connection guide
├── Makefile               # Common developer tasks
├── Dockerfile             # Container build configuration
├── CODE_OF_CONDUCT.md     # Community guidelines
├── CONTRIBUTING.md        # Contribution guide
└── SECURITY.md            # Security policy