Mcptest

🚀 MCP集成服务器（Salesforce • Atlassian • Supabase）

MCP集成服务器是一个用TypeScript编写的模型上下文协议（MCP）服务器，它能将Salesforce、Atlassian（Jira/Confluence）以及内部资源以标准化的方式作为工具和资源暴露出来，供代理调用。

🚀 快速开始

本README文档涵盖以下内容：

• 服务器的功能
• 如何配置凭证
• 如何在本地构建和运行
• 如何在不使用任何桌面客户端的情况下对工具进行冒烟测试
• 操作/安全注意事项

🔍 整体概述

• 语言/运行时：基于Node 18+（推荐Node 20+）的TypeScript
• MCP传输方式：标准输入输出（MCP服务器由客户端启动，并通过标准输入输出进行通信）
• 关键集成：Salesforce REST、Jira/Confluence REST、Supabase（日志记录 + 示例资源）
• 强化功能：带有超时设置的中央HTTP客户端、基本日志编辑、环境隔离

📂 仓库结构

MCPtest-main/
├─ mcp-server/
│  ├─ index.ts                 # MCP服务器（标准输入输出）工具/资源的接线处理程序
│  ├─ types.ts                 # 工具/资源类型辅助文件
│  ├─ runtime/
│  │  ├─ context.ts            # 中央环境 + Supabase客户端
│  │  └─ http.ts               # 共享的axios实例（超时设置、合理的默认值）
│  ├─ tools/
│  │  ├─ salesforce.ts         # salesforce_* 工具（查询/获取/搜索 + 写入）
│  │  ├─ atlassian.ts          # jira_* / confluence_* 工具
│  │  ├─ analytics.ts          # 由Supabase支持的示例工具
│  │  ├─ documents.ts          # 由Supabase支持的示例文档工具
│  │  └─ utilities.ts          # 计算、格式化日期、生成UUID、哈希字符串、HTTP请求
│  ├─ resources/
│  │  ├─ salesforce.ts         # salesforce://* 只读资源
│  │  ├─ atlassian.ts          # jira://* / confluence://* 资源
│  │  ├─ analytics.ts          # 来自Supabase的analytics://* 资源
│  │  └─ documents.ts          # 来自Supabase的document://* 资源
│  └─ tsconfig.json
├─ scripts/
│  ├─ mcp-smoketest.mjs        # 无头工具调用程序（通过标准输入输出启动服务器）
│  └─ list-tools.mjs           # 打印所有工具名称
├─ .env.example
├─ package.json
└─ README.md

📋 前提条件

• Node.js 18+（推荐20+）
• 支持TypeScript的编辑器
• （可选）Salesforce、Jira、Confluence、Supabase的账户/API令牌

⚙️ 环境变量

将项目根目录下的.env.example复制为.env，并填写所需信息。仅需设置你使用的集成项。

Supabase（用于日志记录 + 示例资源）

runtime/context.ts 仍然会读取向后兼容的名称 VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY，但为了清晰起见，建议使用 SUPABASE_* 名称。

Salesforce

Jira（Atlassian）

Confluence（Atlassian）

💡 使用建议

在启用任何写入路径之前，先从只读工具（查询、搜索）开始使用。

📦 安装、构建和本地运行

从项目根目录执行以下操作：

安装依赖

npm install

构建MCP服务器

npm run build:mcp

这将把TypeScript编译为 mcp-server/dist/index.js。

对工具进行冒烟测试（无需桌面客户端）

冒烟测试脚本通过标准输入输出启动MCP服务器，并按名称调用工具。

（可选）显示可用工具：

node scripts/list-tools.mjs

首先调用一个安全工具（来自 utilities.ts），例如：

Mac/Linux

node scripts/mcp-smoketest.mjs calculate '{"expression":"2+2*5"}'

Windows PowerShell（转义引号）

node scripts/mcp-smoketest.mjs calculate "{""expression"":""2+2*5""}"

调用集成工具（仅在设置好 .env 之后），例如：

Salesforce（只读）

node scripts/mcp-smoketest.mjs salesforce_query '{"query":"SELECT Id, Name FROM Account LIMIT 1"}'

Jira（搜索）

node scripts/mcp-smoketest.mjs jira_search_issues '{"jql":"assignee = currentUser() ORDER BY created DESC"}'

你应该看到的输出是一个JSON，其中包含一个 content 数组，该数组包含工具的结果（以文本序列化的JSON形式）。如果出现身份验证错误，请重新检查你的 .env 文件。

🔧 工作原理（简要版）

mcp-server/index.ts 通过标准输入输出启动一个JSON-RPC MCP服务器，处理以下操作：

• ListTools：发现所有工具（来自 tools/ 目录）
• CallTool：将工具调用路由到正确的处理程序
• ListResources/ReadResource：暴露只读的文档/分析/Salesforce/Atlassian资源

mcp-server/runtime/context.ts 集中处理：

• 环境变量解析
• Supabase客户端创建

mcp-server/runtime/http.ts 提供一个共享的axios实例，具有以下特性：

• 20秒超时
• 可控的状态处理

工具会将日志记录到Supabase的 api_logs 表中（如果已配置）。参数会通过一个小型的编辑辅助程序进行处理，以避免存储敏感信息。

📝 配置细节

HTTP客户端

mcp-server/runtime/http.ts 设置了20秒的超时时间和友好的状态处理（validateStatus）。如果你需要重试机制，只需在那里添加一个axios拦截器即可。

日志记录

工具处理程序调用 logApiCall 辅助函数，将记录插入到 api_logs 表中。在插入之前，会对敏感字段（如令牌）进行编辑。

响应

工具始终返回 { content: [{ type: "text", text: "<JSON-string>" }] }。这使得客户端在不同运行时的解析具有可预测性。

⚠️ 安全注意事项

从只读操作开始

从 salesforce_query 或 jira_search_issues 等工具开始使用。稍后再启用写入操作（创建/更新/删除/过渡）。

保护写入操作

一个简单的模式是要求 confirm: "yes" 或默认设置 dryRun: true，并且仅在明确请求时才执行状态更改调用。（计划：在Salesforce/Atlassian写入工具上添加 dryRun 字段。）

最小权限原则

为每个集成使用必要的最小API作用域。

Supabase的行级安全策略

如果你使用ANON密钥，请设置行级安全策略，以确保日志不是全球可读的。

🛠️ 故障排除

找不到模块 mcp-server/dist/index.js

你跳过了构建步骤或从错误的文件夹运行。 解决方法：运行 npm run build:mcp，然后确保 mcp-server/dist/index.js 存在。

挂起或响应非常缓慢

外部API可能较慢。超时时间设置为20秒；如果需要，可以在 runtime/http.ts 中进行调整。

身份验证错误

仔细检查你的 .env 文件。尝试使用非集成工具（如 calculate）来确认服务器/客户端的连接是否正常。

找不到工具

运行 node scripts/list-tools.mjs 查看确切的工具名称，然后将其传递给冒烟测试。

🚀 扩展功能

添加新的集成

在 mcp-server/tools/yourservice.ts 中创建一个新文件，并注册返回结构化结果的工具。

暴露只读视图

通过 mcp-server/resources/yourservice.ts 使用你自己的URI方案（例如，yourservice://…）暴露只读视图。

使用GUI代理运行时或桌面客户端

如果你以后使用GUI代理运行时或桌面客户端，请将其指向 node mcp-server/dist/index.js 作为MCP标准输入输出服务器。

📜 脚本参考

package.json（根目录）包含以下脚本：

• build:mcp：编译MCP服务器
• mcp:server：直接运行编译后的服务器（通常由客户端启动）
• （可选）tools：列出工具名称
• （可选）smoke：运行冒烟测试的简写