shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcptest

这是一个基于TypeScript的MCP协议服务器，集成了Salesforce、Atlassian(Jira/Confluence)和Supabase等服务，为AI代理提供标准化的工具调用和资源访问接口

article

README

🚀 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（用于日志记录 + 示例资源）

| 变量 | 描述 | | ---- | ---- | | SUPABASE_URL | 你的Supabase项目URL | | SUPABASE_ANON_KEY 或 SUPABASE_SERVICE_ROLE_KEY | 访问Supabase的密钥（以ANON开头；仅在使用适当的行级安全策略时使用服务角色） |

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

Salesforce

| 变量 | 描述 | | ---- | ---- | | SALESFORCE_INSTANCE_URL | 例如，https://your-domain.my.salesforce.com | | SALESFORCE_ACCESS_TOKEN | 具有适当作用域的OAuth/Bearer令牌 |

Jira（Atlassian）

| 变量 | 描述 | | ---- | ---- | | JIRA_URL | 例如，https://your-domain.atlassian.net | | JIRA_EMAIL | Atlassian账户邮箱 | | JIRA_API_TOKEN | 从Atlassian账户生成的API令牌 |

Confluence（Atlassian）

| 变量 | 描述 | | ---- | ---- | | CONFLUENCE_URL | 例如，https://your-domain.atlassian.net/wiki | | CONFLUENCE_EMAIL | Atlassian账户邮箱 | | CONFLUENCE_API_TOKEN | 从Atlassian账户生成的API令牌 |

💡 使用建议

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

📦 安装、构建和本地运行

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

安装依赖

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：运行冒烟测试的简写
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端