因此,mcp
蟒蛇 主控程序 将AI助手连接到 因此™ 文档管理系统通过其WebAPI。
暴露 9组工具 涵盖文档CRUD、查询、工作流管理、关键字词典、用户管理、类别和系统操作。通过每个客户端的访问控制和审计日志记录支持多租户部署。stdio模式零外部依赖——纯Python标准库。
快速开始
先决条件
- Python 3.9+
- 一个具有WebAPI访问权限的实例
- MCP兼容客户端(Claude Code、Claude Desktop、Codex、Cursor等)
配置
创建一个 .env.local 在项目根(或点)中 THEREFORE_ENV_PATH 在另一条路径上):```env
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
看 环境变量 以获取完整参考。
### 跑步```bash
# 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:```bash
pip install fastapi uvicorn
______________________________________________________________________
## MCP客户端配置
### 克劳德桌面/克劳德代码
添加 `~/.claude/claude_desktop_config.json` (桌面)或 `~/.claude/config.json` (代码):```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 在项目根目录中:```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` 在您的工作空间中:```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,然后配置:```yaml
~/.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` 弦。
|工具|操作|
|------|-----------|
| `ask_therefore_expert` |智能路由器——描述任务的正确工具和操作|
| `therefore_system` |连接信息、域信息、服务器版本、JWT/ADFS令牌交换|
| `therefore_categories` |获取信息、按名称解析、列出字段、解析字段、引用表信息和查询、生成配置XML|
| `therefore_documents` |获取、创建、更新、更新索引数据、添加流、删除、复制、签出/签入、撤消签出、获取版本/流/评论/历史/属性、添加评论|
| `therefore_query` |同步查询、异步查询、多类别查询、全文搜索、用户查询、工作流实例查询、引用表查询|
| `therefore_workflow` |获取任务、获取实例、声明、发布、完成、委派、获取历史记录、启动工作流、获取流程列表和定义|
| `therefore_users` |获取连接用户、解析、列表、创建、设置/更改密码、移动许可证、门户用户管理、获取/设置设置、删除|
| `therefore_keywords` |列出字典,获取关键字,添加/更新/删除关键字,获取关键字信息|
| `therefore_knowledge` |搜索API文档,获取工作流程指南,字段类型信息,常见模式,已知怪癖,列出资源,获取实时API帮助|
______________________________________________________________________
## 认证
每个租户支持三种身份验证方法:
### 基本身份验证(最常见)```env
THEREFORE_MYTENANT_AUTH_METHOD=Basic
THEREFORE_MYTENANT_USERNAME=your.username
THEREFORE_MYTENANT_PASSWORD=your-password
持有者令牌```env
THEREFORE_MYTENANT_AUTH_METHOD=Bearer
THEREFORE_MYTENANT_PASSWORD=your-bearer-token
### S2S——可信令牌发行者
对于其中由中央身份验证提供者管理而不是存储在env文件中的“因此”凭据的服务到服务部署:```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:```env
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` 工具调用中的参数
1. 根据参数内容(名称、提示)推断
1. 智能默认设置——如果调用者只能访问一个租户,则自动使用它
1. 粘滞--退回到上次使用的租户
### 客户端访问控制(HTTP模式)
在HTTP模式下运行时,创建 `config/clients.json` 以限制每个API密钥可以访问的租户:```json
{
"api-key-for-team-a": ["acme"],
"api-key-for-team-b": ["acme", "contoso"]
}
客户端通过以下方式进行身份验证 Authorization: Bearer。所有访问都记录在审核日志中。
码头工人```bash
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```bash
# 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 在开始之前,先在项目根目录中。
环境变量
每位租户
| 变量 | 描述 |
|---|---|
THEREFORE_TENANTS |
以逗号分隔的租户密钥列表 |
THEREFORE_DEFAULT_TENANT |
配置多个租户时的默认租户 |
THEREFORE__BASE_URL |
因此,WebAPI基础URL |
THEREFORE__AUTH_METHOD |
Basic, Bearer,或 S2S |
THEREFORE__USERNAME |
用户名(基本身份验证) |
THEREFORE__PASSWORD |
密码或承载令牌 |
THEREFORE__TENANTNAME |
TenantName标头值(默认为URL子域) |
THEREFORE__AUTH_PROVIDER_URL |
令牌颁发者URL(S2S身份验证) |
THEREFORE__BRIDGE_API_KEY |
令牌颁发者的API密钥(S2S身份验证) |
THEREFORE__USER_MAPPING |
S2S令牌请求的用户上下文 |
THEREFORE__ASSIGNEE_ALIASES |
逗号分隔的工作流受让人别名 |
THEREFORE__USER_GROUPS |
逗号分隔的用户组筛选器 |
服务器
| 变量 | 描述 | 默认值 |
|---|---|---|
THEREFORE_ENV_PATH |
通往 .env.local |
项目根 |
THEREFORE_MCP_AUTH_TOKEN |
HTTP端点的全局承载令牌 | 无(打开) |
THEREFORE_CACHE_DIR |
缓存目录 | ./cache |
THEREFORE_DEBUG |
详细的请求/响应日志记录(1/true) |
已禁用 |
THEREFORE_LOCAL_TZ |
日期计算时区 | 系统默认值 |
THEREFORE_WORKFLOW_TIMEOUT_SECONDS |
工作流调用超时 | 240 |
THEREFORE_WORKFLOW_MAX_ROWS |
最大工作流查询行数 | 10000 |
THEREFORE_WORKFLOW_RETRY_TIMEOUT_SECONDS |
重试等待时间 | 480 |
THEREFORE_WORKFLOW_RETRY_COUNT |
重试尝试 | 1 |
建筑```
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`
1. 更新相关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的详细请求/响应日志记录:```bash
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)
许可证
麻省理工学院
归因
建造于 Fybre 在以下人员的协助下 克劳德代码 (人类学)。
