MCP Sap Notes

🚀 SAP Note搜索MCP服務器

本MCP服務器藉助SAP Passport認證和Playwright自動化技術，實現對SAP註釋/知識庫文章的搜索功能。它通過Cursor AI直接訪問SAP註釋和知識庫文章，利用SAP Passport證書認證和Playwright瀏覽器自動化從SAP系統中獲取實際的註釋內容。

🚀 快速開始

前提條件

• Node.js 18+ - 在此下載
• SAP Passport證書 - 你個人的.pfx證書文件
• Cursor AI - 在此下載

安裝

1. 克隆倉庫

   git clone https://github.com/marianfoo/mcp-sap-notes
   cd mcp-sap-notes
   

2. 安裝依賴

   npm install
   

3. 構建項目

   npm run build
   

配置

1. 獲取你的SAP Passport證書 - 僅適用於S用戶

   • 訪問 SAP Passport
   • 創建你的證書
   • 下載.pfx證書文件

2. 創建證書目錄

   mkdir certs
   

3. 複製你的SAP Passport證書

   • 將你的.pfx證書文件放在certs/目錄下
   • 將其命名為sap.pfx（或者在配置中更新路徑）

4. 配置環境

   cp .env.example .env
   

   編輯.env文件並添加你的證書密碼：

   PFX_PATH=./certs/sap.pfx
   PFX_PASSPHRASE=your_actual_passphrase
   

連接到Cursor

1. 打開Cursor設置 (Cmd/Ctrl + ,)

2. 在settings.json中添加MCP服務器配置：

   {
     "mcpServers": {
       "sap-note-search": {
         "command": "node",
         "args": ["/full/path/to/sap-note-search-mcp/dist/mcp-server.js"]
       }
     }
   }
   

   ⚠️ 重要提示

   將/full/path/to/sap-note-search-mcp替換為你項目目錄的實際完整路徑。

3. 重啟Cursor - SAP註釋工具將出現在你的AI助手界面中。

✨ 主要特性

• 🔍 直接訪問SAP註釋 - 檢索完整的註釋內容和元數據
• 🎫 SAP Passport認證 - 基於證書的安全認證方式
• 🤖 Playwright自動化 - 處理複雜的SAP認證流程
• 💾 智能緩存 - 本地緩存認證令牌
• 🔧 便於調試 - 提供全面的日誌記錄和故障排除選項
• 📋 符合MCP標準 - 與Cursor AI無縫協作

💻 使用示例

基礎用法

搜索特定的SAP註釋

Find SAP Note 2744792

按關鍵字搜索

Search for SAP Notes about "OData gateway metadata error"

獲取完整的註釋詳情

Get the full content of SAP Note 2744792

📚 詳細文檔

🛠️ 測試與開發

測試認證

npm run test:auth

此命令用於測試SAP Passport認證流程並驗證你的證書配置。

測試API訪問

npm run test:api

此命令用於測試SAP註釋API集成和內容提取功能。

測試完整的MCP服務器

npm run test:mcp

此命令用於模擬完整的MCP服務器工作流程。

運行所有測試

npm run test

🐛 故障排除

證書問題

錯誤信息："Certificate file not found"

• 確保你配置中的證書路徑正確
• 在Cursor的settings.json中使用完整的絕對路徑
• 驗證證書文件存在且可讀

錯誤信息："Authentication failed"

• 檢查你的證書密碼是否正確
• 確保你的SAP Passport證書有效且未過期
• 嘗試使用HEADFUL=true運行以查看瀏覽器認證過程

瀏覽器問題

錯誤信息："Browser launch failed"

# 安裝Playwright瀏覽器
npx playwright install

認證掛起或超時

• 以調試模式運行：HEADFUL=true npm run test:auth
• 檢查你與SAP系統的網絡連接
• 驗證你的證書是否具有對SAP系統的正確訪問權限

MCP集成問題

工具未在Cursor中顯示

• 完全重啟Cursor
• 檢查settings.json中的MCP服務器路徑是否為絕對路徑
• 驗證cwd設置是否指向你的項目目錄

錯誤信息："MCP server failed to start"

• 檢查Cursor開發者工具中的控制檯輸出
• 確保所有依賴項已安裝：npm install
• 驗證構建是否成功完成：npm run build

調試模式

啟用調試模式以進行詳細的故障排除：

# 設置調試環境變量
export HEADFUL=true
export LOG_LEVEL=debug

# 以可見瀏覽器模式運行測試
npm run test:auth

📁 項目結構

sap-note-search-mcp/
├── src/
│   ├── mcp-server.ts        # 主MCP服務器
│   ├── auth.ts              # SAP認證
│   ├── sap-notes-api.ts     # SAP註釋API客戶端
│   ├── types.ts             # TypeScript定義
│   └── logger.ts            # 日誌配置
├── test/
│   ├── test-auth.js         # 認證測試
│   ├── test-sap-api.js      # API測試
│   └── test-mcp-server.js   # 完整服務器測試
├── dist/                    # 編譯後的JavaScript
├── certs/                   # 證書目錄
├── .env.example             # 環境模板
└── README.md               # 本文件

⚙️ 配置

環境變量

Playwright配置

服務器會自動安裝所需的Playwright依賴項。如需手動安裝：

npx playwright install chromium

🔒 安全

• 證書安全：你的SAP Passport證書不會離開你的設備
• 令牌緩存：認證令牌在本地緩存並自動過期
• 無數據存儲：按需檢索SAP註釋內容，不進行存儲
• 安全通信：所有SAP API調用均使用帶有證書認證的HTTPS協議

📋 可用工具

sap_note_search

通過註釋ID或關鍵字搜索SAP註釋和知識庫文章。

參數：

• q（字符串，必需）：查詢字符串或註釋ID
• lang（字符串，可選）：語言代碼（"EN" 或 "DE"），默認為 "EN"

sap_note_get

檢索特定SAP註釋的完整內容和元數據。

參數：

• id（字符串，必需）：SAP註釋ID（6 - 8位數字）
• lang（字符串，可選）：語言代碼（"EN" 或 "DE"），默認為 "EN"

🤝 貢獻代碼

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature/amazing-feature
3. 提交你的更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 打開拉取請求

📄 許可證

本項目採用 Apache 2.0 許可證。