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：運行冒煙測試的簡寫