ProjectSight MCP服务器

一个可扩展、可维护的MCP（模型上下文协议）服务器，通过 425工具 穿过 48个域名--包括项目组合、项目、行动项、RFI、提交文件、合同、预算、付款申请、变更单、每日报告、图纸、文件、会议等。

该服务器已被重构为模块化、可教的结构 展示了构建MCP服务器的最佳实践。它的设计既是生产就绪的，也是一个优秀的学习资源。

🎯 特性

48个领域的425个工具：完整的ProjectSight API覆盖范围—操作项目、RFI、提交资料、项目、组合、合同、预算、付款申请、变更单（潜在/主要/次要）、每日报告、现场工作指示、图纸、图纸集、文件/文件夹、会议、通知、安全通知、剩余工作清单、问题、检查表、预测、工作成本、采购订单、发票、ERP只读、用户、角色、公司、联系人等。
智能网关：默认情况下，服务器公开一个 projectsight 具有意图匹配功能的工具 35+命名功能 （多工具工作流）定义于 mcp/yaml/capabilities.yaml.Set MCP_GATEWAY_ONLY=0 公开所有425个工具。
服务器策略：默认情况下删除从不运行；创建/更新的可选批准通过 mcp/yaml/policy.yaml 以及环境覆盖(MCP_DELETE_POLICY, MCP_REQUIRE_APPROVAL_FOR_MUTATIONS).
OAuth2身份验证：具有缓存和刷新功能的自动令牌管理； 客户端凭证 （STDIO）或 代表代币交换 （例如Agent Studio）。
模块化架构：干净的关注点分离，注册表驱动的网关，易于扩展。
调试工具：测试连接、调试令牌、获取上下文要求、测试不同范围。

📁 项目结构

projectsight-mcp/
├── mcp/
│   ├── main.py                 # Entry point (STDIO or --http)
│   ├── config.py               # Env config; portfolio/scope resolution
│   ├── request_context.py      # Per-request context (actor token, X-* headers)
│   ├── auth.py                 # OAuth2 client credentials + On-Behalf exchange
│   ├── client.py               # ProjectSight API client (retry, token refresh)
│   ├── utils.py                # Helpers (e.g. resolve_project)
│   ├── registry.py             # Load tool_registry.yaml; HANDLER_REGISTRY
│   ├── policy.py               # Delete/mutation policy from policy.yaml + env
│   ├── yaml/
│   │   ├── policy.yaml         # delete_policy, mutation_approval
│   │   ├── tool_registry.yaml  # Tool metadata for gateway (425 tools)
│   │   └── capabilities.yaml   # Named multi-tool workflows (35+ capabilities)
│   ├── scripts/
│   │   └── build_registry.py   # Generate tool_registry.yaml from tool modules
│   ├── docs/
│   │   ├── TOOL_STANDARD.md    # Docstring and registry standards
│   │   └── TOOL_REGISTRY_MAINTENANCE.md  # How to maintain/regenerate registry
│   ├── tools/                  # MCP tools organized by domain
│   │   ├── __init__.py         # register_tools(); gateway-only vs all-tools
│   │   ├── gateway.py         # projectsight(user_request, context, prefer_discovery)
│   │   ├── debug.py            # test_connection, debug_token, get_mcp_context_requirements
│   │   ├── projects.py, portfolio.py
│   │   ├── action_items.py, rfis.py, submittals.py, workflow.py, workflow_states.py
│   │   ├── application_for_payment.py, budget.py, budget_code_structure.py, budget_group.py, budget_snapshot.py
│   │   ├── change_order_request.py, potential_co.py, prime_contract_co.py, sub_contract_co.py
│   │   ├── checklist.py, company.py, contact.py, contract.py, contract_invoice.py
│   │   ├── daily_report.py, drawing.py, drawing_set.py, erp_read_only.py
│   │   ├── field_work_directive.py, file.py, folder.py, forecast.py, general_invoice.py
│   │   ├── issue.py, job_costs.py, lookup_list.py, meeting.py, notice.py
│   │   ├── photo.py, po_catalog.py, purchase_order.py, records.py, report_generator.py
│   │   ├── role.py, safety_notice.py, submittal_package.py, transmittal.py, user.py
│   │   └── punch_list.py
│   └── tests/
│       └── test_gateway_intent.py   # Registry + intent-matching tests
├── README.md
├── pyproject.toml
└── .env                          # Create this; not committed

工具模块在MCP实例和 HANDLER_REGISTRY 因此网关可以按名称执行它们。

🚀 快速开始

1.安装依赖项

pip install fastmcp python-dotenv aiohttp uvicorn pyyaml

或者使用虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install fastmcp python-dotenv aiohttp uvicorn pyyaml

（Pyyaml由注册表和策略模块使用。）

2.配置凭据

创建一个 .env 文件在 mcp/ 具有ProjectSight API凭据的目录（或项目根目录）：

APPLICATION_NAME=your_app_name
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
PROJECTSIGHT_API_URL=https://cloud.api.trimble.com/projectsight/us1/1.0
PROJECTSIGHT_SCOPE=ProjectSight_-_US1
# Optional: PORTFOLIO_ID=your_portfolio_guid (UUID). If unset, the server discovers a default via GET /accounts and GET /accounts/{accountId}/portfolios at startup.
# Optional: for stage or other envs use TRIMBLE_TOKEN_URL=https://stage.id.trimblecloud.com/oauth/token

关于投资组合ID的说明： PORTFOLIO_ID 是 可选的.如果未设置，则服务器调用ProjectSight API(GET /accounts 和 GET /accounts/{accountId}/portfolios)在创业时，使用第一个（或唯一一个）发现的投资组合。您还可以通过以下方式发现账户和投资组合 获取计数 和 get_portfolios_for_account，然后设置 PORTFOLIO_ID 将.env转换为投资组合GUID（UUID）或密码 portfolio_guid 工具调用。API基本URL保持不变(PROJECTSIGHT_API_URL)；所有请求，包括帐户/投资组合发现，都使用它。

获取凭据：

登录 API云使用您的Trimble帐户
在“发现API”页面上，选择 ProjectSight 或 ProjectSight欧盟
选择订阅并订阅您的应用程序
选择 获取密钥 并复制：

- 应用程序名称 - 消费者密钥（CLIENT_ID） - 消费者秘密（CLIENT_Secret）

如需更多信息，请发送电子邮件至 ProjectSightAPISupport@trimble.com 请求API访问。

范围说明：The PROJECTSIGHT_SCOPE 应与您的API订阅区域相匹配：

ProjectSight_-_US1 美国地区
ProjectSight_-_EU1 欧盟地区
ProjectSight_-_US2 适用于Azure美国地区

3.运行服务器

逃离 mcp/ 目录，以便 .env 导入正确解析（或设置 PYTHONPATH 并确保 .env 从正确的位置装载）。

STDIO模式（MCP客户端的默认模式）：

cd mcp
python main.py

HTTP流模式：

cd mcp
python main.py --http

使用自定义主机/端口：

# Windows PowerShell
$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
python main.py --http

# Linux/Mac
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
python main.py --http

仅网关模式（默认）：\ 服务器默认只公开智能 projectsight 网关工具，这样代理就不会被数百个工具淹没。无需配置。要公开所有工具（例如用于调试），请设置 MCP_GATEWAY_ONLY=0 在开始之前。请参阅下面的“智能网关工具”。

端口已在使用中（10048）： 如果在运行时看到“端口已在使用中”或错误10048 python main.py --http，使用另一个端口：set MCP_PORT=8001 （PowerShell： $env:MCP_PORT="8001")，然后重新启动服务器并使用 http://localhost:8001/mcp 在你的客户。要在Windows上释放端口8000：运行 netstat -ano | findstr :8000，记下PID（最后一列），然后 taskkill /PID /F.

🔧 MCP客户端配置

STDIO模式（光标、克劳德桌面等）

{
    "mcpServers": {
        "projectsight": {
            "command": "python",
            "args": ["C:\\Users\\cforey\\Desktop\\projectsight-mcp\\mcp\\main.py"],
            "env": {
                "APPLICATION_NAME": "your_app_name",
                "CLIENT_ID": "your_client_id",
                "CLIENT_SECRET": "your_client_secret",
                "PORTFOLIO_ID": "your-portfolio-guid",
                "MCP_GATEWAY_ONLY": "1"
            }
        }
    }
}

备注：您也可以使用 .env 文件，而不是在配置中设置环境变量。该脚本将自动从 .env 文件在 mcp/ 目录。 PORTFOLIO_ID 可以省略；服务器将在启动时发现默认投资组合。 MCP_GATEWAY_ONLY=1 是默认值（单刀模式）；包括在内 env 使Cursor和其他客户端的行为明确。

HTTP模式

对于支持HTTP传输的MCP客户端，配置连接URL：

http://localhost:8000/mcp

代表演员代币（Agent Studio）

当从以下位置使用MCP时 Trimble代理工作室 （或发送登录用户Trimble ID令牌的任何客户端），您可以使用以下配置MCP “代表演员令牌” 而不是静态凭据。客户端将用户的TID令牌发送为 Authorization: Bearer 每一个请求。然后，MCP通过Trimble Identity将该令牌交换为ProjectSight范围的令牌 代表/代币交换 grant并将其用于API调用，因此请求以该用户的身份运行。

令牌格式： Bearer令牌必须是 JWT公司 （例如Trimble ID令牌）。MCP检测JWT形状并发送正确的 subject_token_type 为了交换。如果你看到一个错误，比如 subject_token type 'urn:ietf:params:oauth:token-type:access_token' not supported，确保客户端在中发送JWT Authorization: Bearer，而不是不透明的访问令牌。

Agent Studio中的安装程序：

身份验证： 选择 代表演员代币.
网址： 您的MCP端点（例如。 https://your-mcp-host/mcp).从Studio使用时，MCP必须可以通过HTTPS访问。
范围（信息性）： 用户令牌的所需范围通常包括：

- openid - 您所在地区的ProjectSight范围： ProjectSight_-_US1 （美国）， ProjectSight_-_EU1 （欧盟），或 ProjectSight_-_US2 （Azure美国）。

确认确切的作用域名称 Trimble身份和 API终点针对您的环境（stage vs prod）。

服务器端： MCP仍然需要 CLIENT_ID 和 CLIENT_SECRET 在 .env （或环境）执行代表代币交换。集 APPLICATION_NAME, PROJECTSIGHT_SCOPE, PORTFOLIO_ID，以及 PROJECTSIGHT_API_URL 违约；每个请求都可以通过标头覆盖它们（见下文）。

可选的每个请求标头（当网关或客户端发送它们时）：

X-Portfolio-Id --请求的投资组合GUID（覆盖 PORTFOLIO_ID 对于该请求）。
X-API-Base-URL -ProjectSight API基本URL（例如，用于不同的区域）。
X-ProjectSight-Scope --用于代币交换的范围（例如。 ProjectSight_-_US1).
X-Application-Name --令牌/作用域的应用程序名称。

如果未发送这些标头，MCP将使用 .env 默认值和工具参数（例如。 portfolio_guid)就像今天一样。

退路： 当否 Authorization: Bearer 令牌存在（例如Studio中的STDIO或“无”身份验证），MCP使用 客户端凭证 从 .env 像以前一样。

代表交易所故障排除：

错误	原因	该怎么办
`JWT error: Signature verification failed`	承载令牌不是由MCP使用的同一Trimble Identity环境颁发的（或无法由其验证）。	确保 TRIMBLE_TOKEN_URL 在 `.env` 与发出令牌的IdP匹配。对于舞台（例如studio.step.trimble-ai.com）使用舞台令牌URL（例如。 `https://stage.id.trimblecloud.com/oauth/token` 或根据Trimble文件）；为了生产使用 `https://id.trimble.com/oauth/token`。客户端必须从同一环境中获取令牌。
`Caller is not the intended audience of subject token`	JWT是为另一种应用而发布的；Trimble Identity不会将其兑换为此MCP的CLIENT_ID的令牌。	确保MCP的客户端ID （in `.env`)是用户登录的应用程序，还是客户端（例如Agent Studio）请求的令牌具有观众（或资源），包括此MCP的应用程序。配置客户端/IdP，使主题令牌 `aud` 包括MCP的CLIENT_ID
`subject_token type 'access_token' not supported`	IdP希望有一个JWT。	当令牌看起来像JWT时，MCP现在会发送JWT类型。确保客户端发送JWT `Authorization: Bearer`.

代表失败时自动回退： 如果代表代币交换失败（例如签名验证或预期受众），MCP 自动回退到客户端凭据 因此仍然可以进行API请求。集 投资组合_ID 在 .env 如果发现没有找到投资组合，或者你需要一个特定的投资组合。然后，请求将使用应用程序标识（而不是登录用户）运行。

未配置“代表”时的解决方法： 省略Bearer令牌（仅使用客户端凭据），设置 投资组合_ID 在 .env，MCP将使用缓存的client_credentials令牌进行发现和所有工具。

🧠 智能网关工具（单工具模式）

默认情况下（或当 MCP_GATEWAY_ONLY=1)，服务器公开一个工具 projectsight 因此，代理不会被数百个工具淹没。集 MCP_GATEWAY_ONLY=0 露出所有工具。

命名功能： 网关可以运行 命名能力 （例如。 project_overview, contract_and_budget_summary, quality_and_issues)它们执行具有共享上下文的固定工具序列。列表在 mcp/yaml/能力.yaml.

参数：

用户请求 （必填）：自然语言请求（例如“列出市中心项目的提交文件”、“获取项目”、“测试连接”）。
上下文 （可选）：使用前几回合的已知上下文听写： portfolio_guid, project_id, project_name, contract_id等等。
prefer_discovery （可选）：如果 true，只返回一个计划（哪些工具将运行），而不执行。

响应：

操作：“need_more_info” --询问用户 questions_for_user，然后再次致电 context 更新（例如用户说“市中心”→ send context: { "project_name": "Downtown" }).
行动：“计划” --何时 prefer_discovery=true，返回将运行的步骤（不执行）。
动作：“结果” --执行工具的结果。
操作：“policy_blocked” --请求删除；此服务器不运行delete命令（删除操作需要三重检查）。
操作：“需要批准” --请求创建/更新，服务器配置为需要批准；再次拨打相同的请求 context 加 approved: true 或 confirm_mutation: true 执行。
操作：“错误” --错误和建议。

服务器策略（不删除；创建/更新的可选批准）：

删除： 服务器不执行删除命令。删除请求返回 action: "policy_blocked" 带有删除操作需要三重检查的消息；使用ProjectSight UI或API进行删除。
创建/更新： 通过设置，您可以在运行创建/更新工具之前要求批准 MCP_REQUIRE_APPROVAL_FOR_MUTATIONS=1。然后，第一个调用返回 action: "approval_required" 有计划；代理或用户可以通过使用相同的上下文加再次调用来确认 approved: true 或 confirm_mutation: true策略已在中配置 mcp/yaml/policy.yaml 并被覆盖 MCP_DELETE_POLICY 和 MCP_REQUIRE_APPROVAL_FOR_MUTATIONS 在 .env.

为代理推荐的工作流程：

用户发送消息。
客服电话 projectsight(user_request=user_message, context={}).
如果响应是 need_more信息 → 代理向用户询问返回的问题，然后调用 projectsight(user_request=..., context={ ... user answers ... }).
如果响应是计划（与 prefer_discovery=true) → 客服可以与用户确认，然后再次呼叫，无需 prefer_discovery 执行。
如果响应是结果 → 代理将结果呈现给用户。
如果响应是错误 → agent显示错误和建议。

上下文连续性（多回合对话）： 网关是无状态的：每次调用只接收 user_request 和 context 为了那个电话。成功的回应包括 resolved_context （例如。 project_id, project_name, portfolio_guid，以及当相关记录ID（如 rfi_id). 客户应保留此信息 resolved_context 并将其作为 context 关于下一个问题的争论 projectsight 呼叫 这样，后续请求（例如在列出RFI后“将截止日期更改为2月19日”）就可以工作，而无需用户重新指定项目或RFI。当用户引用先前结果中的特定项目（例如“那个”，“RFI 005”）时，客户端应添加相应的ID（例如。 rfi_id: 5)它发送的上下文。

代理人不需要多工具测序；网关解析项目/项目组合上下文，并在服务器端运行正确的内部工具。工具元数据位于 mcp/yaml/tool_registry.yaml；处理程序在启动时注册在 HANDLER_REGISTRY 执行。

📚 可用工具

服务器提供 425工具 穿过 48个域名.完整的工具列表和元数据： mcp/yaml/tool_register.yaml.命名的多工具功能（例如。 project_overview, contract_and_budget_summary, quality_and_issues): mcp/yaml/能力.yaml.使用网关时，呼叫 get_mcp_ctext_requiries（） 用于按域分组的所需上下文和工具。

域名（48）： action_items，application_for_pandition，budget，budget_code_structure，budget-snapshot，change_order_request，checklist，company，contact，contract_invoice，daily_report，debug，drawing，drawing_set，erp_read_only，field_work_directive，file，folder，predictor，general_voice，issue，job_costs，lookup_list，meeting，notice，photo，po_catalog，portfolio，potential_co，prime_contract_co，projects，punch_list，purchase_order，records，report_generator，rfis，role，safety_notice，sub_concontract提交文件包、提交文件、传递、用户、工作流、工作流状态。

常用工具（不使用仅网关模式时）： get_projects、list_action_items、list_rfis、list_subittals、test_connection、get_mcp_ctext_requiries。当工具要求时，使用相应的列表/获取工具来发现ID（例如list_contracts、list_budgets） project_id, contract_id等等。投资组合级工具的使用 portfolio_guid 从参数或 PORTFOLIO_ID 从 .env （必须是投资组合GUID/UUID）。

🏗️ 架构和最佳实践

此MCP服务器使用 可扩展、可维护的结构 使用注册表驱动的网关。

架构和数据流

启动： main.py 加载Config，创建Auth和ProjectSightClient，并调用 register_tools(mcp, client).In tools/__init__.py，如果 MCP_GATEWAY_ONLY=1 （默认），内部工具模块向无操作MCP注册，因此它们不会在客户端显示为工具，但它们仍然在中注册处理程序 HANDLER_REGISTRY网关始终注册单个 projectsight 真正的MCP上的工具。
网关流量： 用户呼叫 projectsight(user_request, context?, prefer_discovery?) → 基于关键字的意图匹配 mcp/yaml/tool_registry.yaml 和 mcp/yaml/capabilities.yaml → 解决 portfolio_guid/project_id （和项目名称）通过 utils.resolve_project 以及配置/请求上下文→ 策略检查（删除已阻止的；如果需要，则批准突变）→ 从执行处理程序 HANDLER_REGISTRY → 返回 need_more_info | plan | result | policy_blocked | approval_required | error.
请求上下文（HTTP）： request_context.py 持有每个请求的参与者令牌并覆盖(X-Portfolio-Id, X-API-Base-URL, X-ProjectSight-Scope, X-Application-Name).Auth和Config在存在时使用这些（例如Agent Studio）。
政策： policy.py 读取 mcp/yaml/policy.yaml；环境变量 MCP_DELETE_POLICY 和 MCP_REQUIRE_APPROVAL_FOR_MUTATIONS 以（权力）否决默认情况下从不运行删除操作；创建/更新可能需要 context.approved 或 context.confirm_mutation.

flowchart LR
  User --> projectsight
  projectsight --> IntentMatch
  IntentMatch --> ContextResolve
  ContextResolve --> PolicyCheck
  PolicyCheck --> Handlers
  Handlers --> Response

模块化设计：每个组件都有自己的文件，责任明确。
关注点分离：配置、身份验证、API客户端、注册表、策略和工具是分开的。
有组织的工具：按领域分组的工具；网关使用注册表和功能进行意图匹配。

📖 文档

TOOL_STANDARD.md：工具的文件串和注册表标准；身体/骰子期望。
工具_工具_维护.md：如何保养或再生 mcp/yaml/tool_registry.yaml （例如跑步 python scripts/build_registry.py 从 mcp/).

测试

网关意图匹配测试已上线 mcp/tests/.把他们从 mcp 目录：

cd mcp
python -m unittest tests.test_gateway_intent -v

测试包括注册表加载、常见短语的意图匹配（例如“列表提交”、“获取项目”）和功能提示摘要。

🎓 学习资源

该结构旨在成为 教学实例 -在构建自己的MCP服务器时，请将其作为参考！该代码演示了：

✅ 单一责任原则
✅ 关注点分离
✅ 依赖注入
✅ DRY（不要重复自己）
✅ 明确的命名约定
✅ 全面文档
✅ 类型提示
✅ 错误处理模式

🔐 认证

服务器使用带有Trimble Identity的OAuth2客户端凭据流：

令牌会自动缓存和刷新
令牌缓存存储在 ~/.cache/projectsight/token_cache.json
令牌过期时会自动刷新

📝 重要提示

投资组合ID：.env中的可选项。未设置时，服务器在启动时通过帐户/投资组合API发现默认投资组合。使用 获取计数 和 get_portfolios_for_account 列出帐户和投资组合，然后设置 PORTFOLIO_ID 转换为投资组合GUID（UUID）或密码 portfolio_guid 工具。如果 PORTFOLIO_ID 是一个整数（帐户ID），您必须传递 portfolio_guid 按请求或集合 PORTFOLIO_ID 转换为UUID。

服务器行为（环境）： MCP_GATEWAY_ONLY （默认值 1 =仅限 projectsight 工具； 0 =暴露所有425个工具）。 MCP_DELETE_POLICY （默认值 never_run；删除永远不会执行）。 MCP_REQUIRE_APPROVAL_FOR_MUTATIONS （设置为 1 要求 context.approved 或 context.confirm_mutation 在创建/更新工具运行之前）。可选： MCP_REQUEST_TIMEOUT_SECONDS, MCP_CLIENT_RETRY_COUNT.

项目查找：如果您不知道项目ID，许多工具支持按名称查找项目（不区分大小写，部分匹配）。

RFI创建：The create_or_update_rfi 该工具非常灵活，将：

- 从现有RFI中自动检测工作流状态 - 自动生成RFI编号 - 将各种格式的日期标准化（“今天”、“明天”、“2026-01-26”等） - 将重要性文本（“高”、“正常”、“低”）映射到重要性ID - 在适当的时候使用现有的RFI设置作为默认值

🌐 通过公共URL公开（隧道）

要通过公共URL访问本地服务器，请使用隧道服务：

选项1:ngrok（推荐）

在Windows上安装ngrok:

   winget install ngrok.ngrok

启动MCP服务器:

   cd mcp
   python main.py --http

创建隧道 （在单独的终端中）：

   ngrok http 8000

使用公共URL：ngrok将提供一个公共URL，如 https://abc123.ngrok-free.dev.

MCP端点位于 /mcp:

   https://abc123.ngrok-free.dev/mcp

选项2:Cloudflare隧道（cloudflared）

安装cloudflared：从下载 developers.cloudflare.com

启动MCP服务器:

   cd mcp
   python main.py --http

创建隧道 （在单独的终端中）：

   cloudflared tunnel --url http://localhost:8000

使用公共URL：Cloudflare将提供一个公共URL，如 https://random-subdomain.trycloudflare.com。您的MCP终点将是：

   https://random-subdomain.trycloudflare.com/mcp

🔒 安全说明

当公开您的服务器时，请考虑：

如果MCP服务器处理敏感数据，则添加身份验证/API密钥
使用HTTPS（上述所有隧道服务都提供HTTPS）
如果可能，限制对特定IP的访问
监控使用情况和速率限制

📊 速率限制

根据Trimble Cloud的更新指南，您不需要将x-API-key传递到trimblepaas.com端点。如果您确实通过了它，则每秒限制为50个请求。

📖 API 文档

有关API的详细文档，请参阅：

ProjectSight API文档

🔄 从旧结构迁移

如果你用的是旧的 projectsight.py 直接文件：

更新命令：使用 python main.py 而不是 python projectsight.py
配置：相同 .env 文件格式（放置在 mcp/ 目录）
MCP客户端配置：更新指向的路径 mcp/main.py
工具：所有工具都一样，只是组织得更好

旧的 projectsight.py 该文件仍可供参考，但建议使用新的模块化结构。

🛠️ 扩展服务器

新工具 生活在…之下 mcp/tools/.py每个工具模块定义 register(mcp, handler_registry) 并注册FastMCP工具和异步处理程序： handler_registry[name] = my_async_handler网关通过以下方式按名称执行工具 get_handler(name) 从注册表。
网关意图匹配： 在中添加（或重新生成）工具条目 mcp/yaml/tool_registry.yaml （名称、描述、域、required_context、optional context、关键字；可选示例、follow_ups）。跑 python scripts/build_registry.py 从 mcp/ 目录，用于从文档字符串重新生成注册表；看见工具_工具_维护.md.
装电线： 将新模块添加到导入中 register(...) 来电 mcp/tools/__init__.py。可选：如果该工具是多步骤工作流的一部分，请在中添加或扩展条目 mcp/yaml/capabilities.yaml.

示例模式：

# mcp/tools/my_domain.py
from fastmcp import FastMCP

_client = None

def register(mcp: FastMCP, handler_registry: dict):
    @mcp.tool()
    async def my_tool(portfolio_guid: str, param: str) -> dict:
        """One-line summary. Args: portfolio_guid: ... param: ... Returns: ..."""
        return await _run_my_tool(portfolio_guid, param)

    handler_registry["my_tool"] = _run_my_tool  # gateway executes by name

async def _run_my_tool(portfolio_guid: str, param: str) -> dict:
    result = await _client.get(f"/{portfolio_guid}/endpoint/{param}")
    return {"result": result}

def set_client(client):
    global _client
    _client = client

📄 许可证

本项目以i的形式提供，以便与ProjectSight API一起使用。

______________________________________________________________________

基于最佳实践构建 -使用此结构作为构建自己的MCP服务器的参考！ 🚀

Project Sight MCP

快速接入

详细介绍