金大哥 - mcp-sap-notes MCP 详情

article

README

🚀 SAP Note搜索MCP服务器

本MCP服务器借助SAP Passport认证和Playwright自动化技术，实现对SAP注释/知识库文章的搜索功能。它通过Cursor AI直接访问SAP注释和知识库文章，利用SAP Passport证书认证和Playwright浏览器自动化从SAP系统中获取实际的注释内容。

🚀 快速开始

前提条件

Node.js 18+ - 在此下载
SAP Passport证书 - 你个人的.pfx证书文件
Cursor AI - 在此下载

安装

克隆仓库

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

安装依赖
```
npm install
```
构建项目
```
npm run build
```

配置

获取你的SAP Passport证书 - 仅适用于S用户
- 访问 SAP Passport
- 创建你的证书
- 下载.pfx证书文件
创建证书目录
```
mkdir certs
```
复制你的SAP Passport证书
- 将你的.pfx证书文件放在certs/目录下
- 将其命名为sap.pfx（或者在配置中更新路径）

配置环境

cp .env.example .env

编辑.env文件并添加你的证书密码：

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

连接到Cursor

打开Cursor设置 (Cmd/Ctrl + ,)

在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替换为你项目目录的实际完整路径。

重启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               # 本文件

⚙️ 配置

环境变量

| 属性 | 详情 | |------|------| | PFX_PATH | 必需。SAP Passport证书（.pfx）的路径 | | PFX_PASSPHRASE | 必需。证书密码 | | MAX_JWT_AGE_H | 可选。默认值为12。令牌缓存的生命周期（小时） | | HEADFUL | 可选。默认值为false。浏览器可见性（用于调试） | | LOG_LEVEL | 可选。默认值为info。日志级别（debug、info、warn、error） |

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"

🤝 贡献代码

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
提交你的更改：git commit -m 'Add amazing feature'
推送到分支：git push origin feature/amazing-feature
打开拉取请求

📄 许可证

本项目采用 Apache 2.0 许可证。

Cursor MCP Server Preview

mcp-sap-notes