Worksection MCP

MCP服务器工作区

 

多租户MCP（模型上下文协议）服务器 工作区 项目管理平台， 建于 FastMCP.

提供 全面的只读工具 对于数据访问， 使像Claude这样的人工智能助手能够生成报告、分析项目数据， 并处理图像附件。

特性

• 多用户 -可配置为任何工作区帐户
• OAuth2身份验证 -自动保护授权码流

令牌刷新

• 全面的只读工具 -项目、任务、评论、时间跟踪、，

用户，以及更多

• 图像分析 -Claude vision用于分析屏幕截图的MCP资源

和附件

• 速率限制 -每个工作区API的内置1 req/sec节流限制
• 文件高速缓存 -下载附件的本地缓存
• 大响应卸载 -超大的工具响应被卸载到磁盘；客户端通过辅助工具以有界块的形式读回它们
• 生产就绪 -具有多阶段构建的Docker容器化
• 可扩展 -用于添加自定义工具的干净架构

快速开始

先决条件

• Python 3.14+
• 紫外线 包管理器
• 具有OAuth2应用程序凭据的工作分区帐户

安装

# Clone the repository
git clone https://github.com/pbv7/worksection-mcp.git
cd worksection-mcp

# Install dependencies with uv (always use --frozen to respect lockfile)
uv sync --frozen --extra dev

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
# Then validate your configuration
uv run python scripts/validate_config.py

# Restrict permissions on the data directory (tokens, keys, certs)
mkdir -p data && chmod 700 data

配置

编辑 .env 使用您的工作区OAuth2凭据：

# Required
WORKSECTION_CLIENT_ID=your_client_id
WORKSECTION_CLIENT_SECRET=your_client_secret
WORKSECTION_ACCOUNT_URL=https://yourcompany.worksection.com

# Optional (defaults shown)
WORKSECTION_REDIRECT_URI=https://localhost:8080/oauth/callback
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8000
MCP_TRANSPORT=streamable-http
LOG_LEVEL=INFO
LOG_USE_COLORS=true
REQUEST_LOG_MODE=INFO
FASTMCP_SHOW_SERVER_BANNER=false

运行服务器

# Development
uv run python -m worksection_mcp

# Or using the entry point
uv run worksection-mcp

首次运行时，服务器将：

1. 打开浏览器进行OAuth2授权
2. 授权后，它将保存加密令牌
3. 在端口8000上启动MCP服务器

Docker部署

# Build the image
docker build -t worksection-mcp .

# Run with environment file
docker run -d \
  --name worksection-mcp \
  -p 8000:8000 \
  -e MCP_SERVER_HOST=0.0.0.0 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  worksection-mcp

# Or use docker-compose
docker compose up -d

OAuth2设置

创建工作区OAuth2应用程序

1. 转到您的工作分区帐户设置
2. 导航到API/集成
3. 创建新的OAuth2应用程序
4. 将重定向URI设置为 https://localhost:8080/oauth/callback

（需要HTTPS）

1. 注意你的 client_id 和 client_secret
2. 启用所需的读取范围：项目、任务、成本、标签、，

评论、文件、人员、联系人

OAuth回调的HTTPS

工作节要求OAuth2重定向URI使用HTTPS。此服务器会自动 首次运行时生成自签名SSL证书。

期待什么：

• 证书自动生成并存储在 ./data/certs/
• 您的浏览器将显示“您的连接不是私有的”警告
• 点击“高级”→ “转到localhost（不安全）”继续
• 这是本地开发中自签名证书的预期

使用自定义证书：

# Set paths to your certificates in .env
OAUTH_SSL_CERT_PATH=/path/to/your/cert.crt
OAUTH_SSL_KEY_PATH=/path/to/your/key.key

禁用SSL（不推荐）：

# Only if you have an alternative HTTPS solution (e.g., ngrok)
OAUTH_CALLBACK_USE_SSL=false

身份验证流程

First Run (no tokens):
1. Server starts callback listener on port 8080
2. Opens browser → Worksection authorization page
3. User grants permissions
4. Callback receives authorization code
5. Server exchanges code for access + refresh tokens
6. Tokens encrypted and saved locally
7. MCP server starts

Subsequent Runs:
1. Load encrypted tokens from storage
2. If access token expired → auto-refresh
3. If refresh token expired → re-authenticate via browser
4. MCP server starts

可用工具

项目

任务

评论

文件

成本和时间

用户和团队

标签

分析

活动

活动工具默认在MCP的1MB响应下返回尽可能多的事件 限制（具有~150KB的安全裕度，没有固定的默认上限）。集 max_results 明确地控制截断。 截断元数据(total_count, returned_count, truncated, truncation_reason) 总是包括在内。

系统

大型响应助手

当工具响应超过 LARGE_RESPONSE_OFFLOAD_THRESHOLD_BYTES，它被卸载到磁盘上 取而代之的是一个紧凑的信封。使用这些工具检查和读取卸载的内容：

MCP资源

资源允许Claude直接访问和分析文件：

利用资源进行图像分析

# In your MCP client or skill:
# 1. Get task discussion with files
discussion = await get_task_discussion(task_id="12345")

# 2. For each image file, access via resource
for file in discussion.get("images", []):
    # Claude can read this resource and analyze the image
    image_content = await read_resource(file["resource_uri"])

配置参考

测试

自动化测试（推荐）

自动测试所有MCP工具：

# Use first available project
uv run python tests/test_all_mcp_tools.py

# Specify project name
uv run python tests/test_all_mcp_tools.py --project "My Project"

这个全面的测试脚本：

• ✅ 测试所有注册的MCP工具
• ✅ 可配置的项目选择（通过CLI参数或环境变量）
• ✅ 自动从项目数据中提取测试ID
• ✅ 提供详细的通过/失败结果
• ✅ 自动处理速率限制

看 测试.md 获取完整的文档和配置选项。

要验证针对真实Workssection帐户的大响应卸载，请执行以下操作：

uv run python tests/live_large_response_offload_roundtrip.py -v

使用MCP检查员进行手动测试

对于交互式测试：

# Start your MCP server
uv run worksection-mcp

# In another terminal, start the MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

发展

设置开发环境

# Install with dev dependencies (use --frozen, never uv pip install)
uv sync --frozen --extra dev

# Run tests
make test-fast

# Run with coverage
make test

# Plain `uv run pytest` uses the same no-coverage mode as `make test-fast`.
# Use `make test` or `make check` when you need coverage output.

# Lint code
make lint

# Lint all Markdown from repo root
make lint-docs

# Auto-fix all Markdown from repo root
npx markdownlint-cli2 --fix

# Type check
make typecheck

# Run the full CI-like check
make check

项目结构

worksection-mcp/
├── src/
│   └── worksection_mcp/
│       ├── __init__.py          # Package init
│       ├── __main__.py          # Entry point
│       ├── server.py            # FastMCP server
│       ├── config/              # Configuration
│       ├── auth/                # OAuth2 authentication
│       ├── client/              # API client
│       ├── tools/               # MCP tools
│       ├── resources/           # MCP resources
│       ├── cache/               # File and session caching
│       ├── large_response.py    # Large tool response offloading
│       └── utils/               # Date formatting, response helpers
├── tests/                       # Test suite
├── data/                        # Runtime data (gitignored)
├── Dockerfile                   # Container build
├── docker-compose.yml           # Local development
└── docker-compose.prod.yml      # Production deployment

部署

Docker生产

# Build production image
docker build -t worksection-mcp:latest .

# Run with production compose
docker compose -f docker-compose.prod.yml up -d

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: worksection-mcp
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: worksection-mcp
        image: worksection-mcp:latest
        ports:
        - containerPort: 8000
        env:
        - name: WORKSECTION_CLIENT_ID
          valueFrom:
            secretKeyRef:
              name: worksection-secrets
              key: client_id
        - name: WORKSECTION_CLIENT_SECRET
          valueFrom:
            secretKeyRef:
              name: worksection-secrets
              key: client_secret
        volumeMounts:
        - name: data
          mountPath: /app/data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: worksection-mcp-data

容器的预认证

由于OAuth2需要浏览器交互，请先在本地进行身份验证：

# 1. Run locally to authenticate
uv run python -m worksection_mcp

# 2. After authentication, tokens are saved to ./data/tokens/

# 3. Mount this directory in your container
docker run -v ./data:/app/data worksection-mcp

故障排除

配置验证

在排除故障之前，请验证您的完整配置：

uv run python scripts/validate_config.py

验证器分3个步骤进行全面检查：

第一步：媒染剂验证 （加载.env时自动）

• OAuth2凭据格式和长度
• URL格式和结构
• 重定向URI HTTPS要求
• 有效的OAuth2作用域名称
• 端口号范围（1-65535）
• 文件大小和保留期为正值
• SSL配置一致性

步骤2：配置摘要

• 显示所有加载的设置
• 显示派生值（API URL）
• 包括日志控制(LOG_LEVEL, LOG_USE_COLORS, REQUEST_LOG_MODE)
• 帮助验证环境变量是否设置正确

步骤3：外部资源检查

• 帐户URL的DNS解析
• 目录写入权限（令牌、缓存、证书）
• 文件系统可访问性

如果验证通过，则配置完成，服务器将成功启动。

OAuth2问题

“重定向URI无效”

• 确保您在工作区中注册的重定向URI完全匹配
• 违约： https://localhost:8080/oauth/callback
• 工作分区需要HTTPS-不要使用 http://

“您的连接不是私有的”浏览器警告

• 这是自签名证书所期望的
• 点击“高级”→ “转到localhost（不安全）”继续
• 警告仅在OAuth授权期间出现

“刷新令牌已过期”

• 删除 ./data/tokens/tokens.enc 并重新验证

SSL证书问题

• 删除 ./data/certs/ 用于重新生成证书的目录
• 确保您对数据目录具有写入权限

配置和连接问题

“无法解析主机名”或“未提供节点名或服务名，或未知”

此DNS解析错误表示无法解析工作分区帐户URL：

检查您的配置：

# Run validation to diagnose
uv run python scripts/validate_config.py

常见原因：

• Typo in WORKSECTION_ACCOUNT_URL 在你的 .env 文件
• 域名缺失或不正确（应 https://yourcompany.worksection.com)
• 没有互联网连接
• 企业防火墙阻止DNS

修复：

1. 验证您的URL .env 与您的实际工作分区帐户匹配
2. 测试DNS解析： nslookup yourcompany.worksection.com
3. 检查互联网连接
4. 尝试其他DNS服务器（8.8.8.8、1.1.1.1）

注： 通过新的验证，此错误在启动时被捕获，并显示一条明确的消息，而不是在运行时被捕获。

启动时出现“验证错误”

服务器现在使用Pydantic在启动时验证所有配置。如果您看到验证错误：

1. 检查错误消息-它告诉你到底出了什么问题
2. 参见 .env.example 正确的格式
3. 常见问题：

- 客户端ID/密码太短（至少8/16个字符） - 重定向URI无效（必须是HTTPS，本地主机除外） - 无效范围（请参阅中的列表 .env.example) - 端口号超出范围（1-65535）

速率限制

429请求太多

• 服务器会自动回退并重试
• API工作区限制：1个请求/秒

文件缓存

“文件太大”

• 增加 MAX_FILE_SIZE_MB 环境变量
• 默认限制：10MB

API约束和限制

API设计工作部分

无分页支持

大多数工作区API终结点返回完整的数据集而不分页：

• get_users -在一次呼叫中返回所有用户
• get_events -返回指定时间段内的所有事件
• get_projects -返回所有项目
• get_all_tasks -返回所有项目中的所有任务
• get_tasks -返回项目的所有任务
• get_project_groups -返回所有项目文件夹

影响：对于大型数据集，响应可能超过MCP的1MB限制。

解决方案：服务器使用两个响应大小控件：

• 中央大型响应卸载存储超大工具结果

LARGE_RESPONSE_OFFLOAD_PATH 并返回一个紧凑的元数据信封，其中包含 卸载ID。

• get_offloaded_response_info 和 read_offloaded_response_text 让客户

检查并读取有界块中的卸载响应。

• 本地 file_path 默认情况下，值是隐藏的；使用 resource_uri 和助手

除非MCP客户端使用受信任的本地文件系统访问运行。

• 默认的50KB卸载阈值和50KB读取限制为JSON留出了空间

MCP客户端中具有严格内联响应的封装和逃逸开销 限制。

• 当JSON转义时，块读取返回的原始字节可能比请求的少

否则会使序列化的辅助工具响应太大。

• 卸载的文件在启动时和未来卸载到期之前会被清理，使用

LARGE_RESPONSE_OFFLOAD_RETENTION_HOURS 和 LARGE_RESPONSE_OFFLOAD_MAX_FILES.

• MCP客户端接受较大内联响应的部署可能会引发

LARGE_RESPONSE_OFFLOAD_THRESHOLD_BYTES 或 LARGE_RESPONSE_MAX_READ_BYTES, 交易更少的卸载/读取调用，以获得更高的上下文和客户限额风险。

• 选定的高容量工具仍然应用特定于端点的截断：

get_activity_log, get_user_activity, search_tasks，以及 get_comments.

截断的响应包括元数据： total_count, returned_count, truncated, truncation_reason.

有关API限制和解决方法的综合列表，请参阅 docs/API-限制.md.

面向客户的实际覆盖范围、限制和预期摘要 PASS/PARTIAL 语义，请参见 docs/CLIENT-CAPABILITIES.md.

范围要求提高

某些端点需要 administrative 范围：

• get_webhooks -Webhook管理
• 其他行政业务

添加 administrative 到 WORKSECTION_SCOPES 在 .env 以启用这些工具。

MCP协议约束

响应大小限制：1MB

错误： "Tool result is too large. Maximum size is 1MB."

模型上下文协议强制最大响应大小为1MB。此服务器处理 通过自动文件卸载和使用产生超大通用工具 针对所选列表/搜索工具的工具特定截断。

网络与安全

默认绑定：127.0.0.1

默认情况下，MCP服务器绑定到 127.0.0.1 （仅限本地主机）以确保安全。

Docker部署：设置 MCP_SERVER_HOST=0.0.0.0 在docker中编写 服务器可从网络访问。

看 .env.example 有关配置详细信息

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

欢迎投稿！请阅读我们的投稿指南并提交pull请求。

支持

• API工作节文档
• MCP文件