Therefore MCP

因此，mcp

蟒蛇 主控程序 将AI助手连接到 因此™ 文档管理系统通过其WebAPI。

暴露 9组工具 涵盖文档CRUD、查询、工作流管理、关键字词典、用户管理、类别和系统操作。通过每个客户端的访问控制和审计日志记录支持多租户部署。stdio模式零外部依赖——纯Python标准库。

快速开始

先决条件

• Python 3.9+
• 一个具有WebAPI访问权限的实例
• MCP兼容客户端（Claude Code、Claude Desktop、Codex、Cursor等）

配置

创建一个 .env.local 在项目根（或点）中 THEREFORE_ENV_PATH 在另一条路径上）：

THEREFORE_TENANTS=mytenant
THEREFORE_DEFAULT_TENANT=mytenant

THEREFORE_MYTENANT_BASE_URL=https://mytenant.thereforeonline.com/theservice/v0001/restun
THEREFORE_MYTENANT_AUTH_METHOD=Basic
THEREFORE_MYTENANT_USERNAME=your.username
THEREFORE_MYTENANT_PASSWORD=your-password
THEREFORE_MYTENANT_TENANTNAME=mytenant

看 环境变量 以获取完整参考。

跑步

# stdio (default) — for MCP clients
python3 src/mcp_server.py

# HTTP/SSE on port 8000
python3 src/mcp_server.py --http 8000

# Both simultaneously
python3 src/mcp_server.py --stdio --http 8000

HTTP模式需要 fastapi 和 uvicorn:

pip install fastapi uvicorn

______________________________________________________________________

MCP客户端配置

克劳德桌面/克劳德代码

添加 ~/.claude/claude_desktop_config.json （桌面）或 ~/.claude/config.json （代码）：

{
  "mcpServers": {
    "therefore": {
      "command": "python3",
      "args": ["/path/to/therefore-mcp/src/mcp_server.py"],
      "env": {
        "THEREFORE_ENV_PATH": "/path/to/therefore-mcp/.env.local"
      }
    }
  }
}

光标

添加 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "therefore": {
      "command": "python3",
      "args": ["/path/to/therefore-mcp/src/mcp_server.py"],
      "env": {
        "THEREFORE_ENV_PATH": "/path/to/therefore-mcp/.env.local"
      }
    }
  }
}

VS代码（副本）

添加 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "therefore": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/therefore-mcp/src/mcp_server.py"],
      "env": {
        "THEREFORE_ENV_PATH": "/path/to/therefore-mcp/.env.local"
      }
    }
  }
}

鹅（HTTP传输）

使用启动服务器 --http 8000，然后配置：

# ~/.config/goose/config.yaml
extensions:
  therefore:
    type: sse
    uri: http://localhost:8000/mcp
    headers:
      Authorization: "Bearer your-secret-token"   # if THEREFORE_MCP_AUTH_TOKEN is set

______________________________________________________________________

工具

工具按域分组。每个工具都需要一个强制性 operation string和必填项 tenant 弦。

______________________________________________________________________

认证

每个租户支持三种身份验证方法：

基本身份验证（最常见）

THEREFORE_MYTENANT_AUTH_METHOD=Basic
THEREFORE_MYTENANT_USERNAME=your.username
THEREFORE_MYTENANT_PASSWORD=your-password

持有者令牌

THEREFORE_MYTENANT_AUTH_METHOD=Bearer
THEREFORE_MYTENANT_PASSWORD=your-bearer-token

S2S——可信令牌发行者

对于其中由中央身份验证提供者管理而不是存储在env文件中的“因此”凭据的服务到服务部署：

THEREFORE_MYTENANT_AUTH_METHOD=S2S
THEREFORE_MYTENANT_AUTH_PROVIDER_URL=https://your-auth-provider/
THEREFORE_MYTENANT_BRIDGE_API_KEY=optional-api-key
THEREFORE_MYTENANT_USER_MAPPING=service-account-name

服务器调用 POST {AUTH_PROVIDER_URL}/issue-token 随着 {"tenant": "...", "user_hint": "..."} 并为每个租户缓存返回的JWT。看 services/auth-provider/ 作为参考实现。

ADFS / 输入 ID

使用 therefore_system → operation: get_connection_token_from_adfs 将预先获得的Entra ID令牌兑换为So JWT。需要v1 ID令牌（RS256，版本：1.0，带 upn 索赔）。看 AUTHENTICATION_README.md 对于全流量和 scripts/ 用于辅助脚本。

______________________________________________________________________

多租户设置

在中定义多个租户 .env.local:

THEREFORE_TENANTS=acme,contoso
THEREFORE_DEFAULT_TENANT=acme

THEREFORE_ACME_BASE_URL=https://acme.thereforeonline.com/theservice/v0001/restun
THEREFORE_ACME_AUTH_METHOD=Basic
THEREFORE_ACME_USERNAME=svc.account
THEREFORE_ACME_PASSWORD=secret
THEREFORE_ACME_TENANTNAME=acme

THEREFORE_CONTOSO_BASE_URL=https://contoso.thereforeonline.com/theservice/v0001/restun
THEREFORE_CONTOSO_AUTH_METHOD=Basic
THEREFORE_CONTOSO_USERNAME=svc.account
THEREFORE_CONTOSO_PASSWORD=secret
THEREFORE_CONTOSO_TENANTNAME=contoso

租户处置令 （根据请求）：

1. 明确的 tenant 工具调用中的参数
2. 根据参数内容（名称、提示）推断
3. 智能默认设置——如果调用者只能访问一个租户，则自动使用它
4. 粘滞--退回到上次使用的租户

客户端访问控制（HTTP模式）

在HTTP模式下运行时，创建 config/clients.json 以限制每个API密钥可以访问的租户：

{
  "api-key-for-team-a": ["acme"],
  "api-key-for-team-b": ["acme", "contoso"]
}

客户端通过以下方式进行身份验证 Authorization: Bearer 。所有访问都记录在审核日志中。

______________________________________________________________________

码头工人

# stdio (default)
docker run --rm -i --env-file /path/to/.env.local fybre/therefore-mcp

# HTTP on port 8000
docker run --rm -p 8000:8000 --env-file /path/to/.env.local fybre/therefore-mcp --http 8000

# Build locally
docker build -t therefore-mcp .
docker run --rm -i --env-file /path/to/.env.local therefore-mcp

Docker Compose

# HTTP mode (production, detached)
docker compose --profile http up -d

# HTTP + optional S2S auth provider
docker compose --profile http --profile auth up -d

# stdio mode
docker compose --profile stdio up

创建 .env.local 在开始之前，先在项目根目录中。

______________________________________________________________________

环境变量

每位租户

服务器

______________________________________________________________________

建筑

src/
  mcp_server.py         # MCP server — 9 grouped tools, operation registry, tenant
  therefore_client.py   # HTTP client — auth, retries, config building, all API methods
  knowledge_tools.py    # Knowledge base utilities for therefore_knowledge tool
config/
  clients.json          # Client API key → tenant access list (HTTP mode)
  clients.json.example  # Template
services/
  auth-provider/        # Reference S2S token issuer implementation
tools/
  config_generator/     # Delta XML generator for Therefore category creation
scripts/
  validate_therefore_api.py      # API connectivity validation
  get_entra_token_device_code.py # Entra ID v1 device code flow
  test_entra_jwt_exchange.py     # Test ADFS/Entra → Therefore JWT exchange
docs/
  therefore-api-complete-guide.md  # Comprehensive API reference
  PYTHON_EXAMPLES.md               # Python code examples
  PYTHON_QUICK_REFERENCE.md        # Quick field type and pattern reference
  knowledge-base.json              # Structured API knowledge (used by therefore_knowledge tool)

保持知识同步

服务器的本地知识库(docs/knowledge-base.json)以及延长降价 文件编制(docs/PYTHON_EXAMPLES.md, docs/PYTHON_QUICK_REFERENCE.md, docs/therefore-api-complete-guide.md)是两个应保持一致的独立层：

• knowledge-base.json --结构化JSON查询 therefore_knowledge 运行时的MCP工具
• Markdown文档——由引用 因此api技能 通过GitHub原始URL

当您发现新的API异常、更新工作流或更正模式时， 更新两者:

1. 在中添加/编辑相关条目 docs/knowledge-base.json
2. 更新相关markdown文档中的相应部分

这 therefore_knowledge 搜索工具将把人工智能助手定向到GitHub文档，作为 如果本地知识库没有令人满意的答案，则回退。

关键设计决策

• 分组工具： 9个域工具 operation 参数，而不是数百个单独的工具。降低MCP工具列表噪音，同时保持完全覆盖。
• 具有访问控制的多租户： 每个客户端API密钥→ 每次工具调用时都强制执行租户分配。所有通话都会被审计记录。
• 模糊匹配： 类别和字段名称已解析 difflib.SequenceMatcher.返回a needs_confirmation 当置信度低于阈值时，标记。
• Web客户端文档流： 文档创建遵循So web客户端使用的四步流程： GetCategoryInfo → PreprocessIndexData → EvaluateConditionalProperties → CreateDocument.
• 异步查询批处理： execute_async_single_query_all 自动获取所有页面，并始终释放服务器会话 finally 块。
• 缓存： 使用300秒TTL缓存的类别、字段和关键字元数据，持久化到 cache/ 每个租户。

______________________________________________________________________

调试

集 THEREFORE_DEBUG=1 有关stderr的详细请求/响应日志记录：

THEREFORE_DEBUG=1 python3 src/mcp_server.py

输出示例：

[THEREFORE] POST https://tenant.thereforeonline.com/.../GetCategoryInfo (142 bytes)
[THEREFORE]  <- 200 OK (3854 bytes, 237ms)
[THEREFORE] POST https://tenant.thereforeonline.com/.../ExecuteAsyncSingleQuery (285 bytes)
[THEREFORE]  <- 200 OK (1204 bytes, 89ms)

______________________________________________________________________

许可证

麻省理工学院

归因