斯尼克-MCP-REST

Name: 斯尼克-MCP-REST
Author: axelspringer

作者：axelspringer2 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

snyk-mcp-rest

这是一个支持内置模型上下文协议（MCP）服务器的TypeScript客户端，用于Snyk REST API。此包提供了从官方Snyk OpenAPI规范自动生成的类型安全API客户端以及用于AI助手集成的MCP服务器。

特性

🔄 自动生成的TypeScript客户端 - 根据官方Snyk OpenAPI规范（2025-11-05）生成
🤖 MCP服务器集成 - 内置用于AI助手（如Claude等）的模型上下文协议服务器
📦 完整的类型安全性 - 全面支持TypeScript和IntelliSense
🔌 基于Axios的HTTP客户端 - 可靠的HTTP操作及错误处理
🧪 全面测试 - 使用Vitest并支持覆盖率报告
🏗️ 模块化架构 - 自动生成代码与自定义代码之间的清晰分离

安装

npm install

构建

构建过程包括OpenAPI代码生成和TypeScript编译：

# 完整构建（生成+编译）
npm run prepare

# 从OpenAPI规范生成API客户端
npm run generate

# 仅编译TypeScript
npm run build

使用

基本API客户端使用

import { Configuration, OrgsApi, IssuesApi } from 'snyk-mcp-rest';

// 配置API客户端
const config = new Configuration({
  apiKey: process.env.SNYK_API_KEY,
  basePath: 'https://api.snyk.io/rest'
});

// 或使用辅助函数
import { createConfiguration } from 'snyk-mcp-rest';
const config = createConfiguration(process.env.SNYK_API_KEY!);

// 使用组织API
const orgsApi = new OrgsApi(config);
const orgs = await orgsApi.listOrgs({ 
  version: '2024-11-05' 
});

// 使用问题API
const issuesApi = new IssuesApi(config);
const issues = await issuesApi.listOrgIssues({
  version: '2024-11-05',
  orgId: 'your-org-id',
  status: ['open'],
  limit: 100
});

// 使用项目API根据仓库名称查找项目
const projectsApi = new ProjectsApi(config);
const projects = await projectsApi.listOrgProjects({
  version: '2024-11-05',
  orgId: 'your-org-id',
  names: ['owner/my-repo']  // 按仓库名称过滤
});

// 获取匹配仓库的项目ID
const projectIds = projects.data.data?.map(p => p.id) || [];

// 获取特定项目的详细问题
if (projectIds.length > 0) {
  const projectIssues = await issuesApi.listOrgIssues({
    version: '2024-11-05',
    orgId: 'your-org-id',
    scanItemId: projectIds[0],
    scanItemType: 'project' as any,
    status: ['open']
  });
}

MCP服务器使用

MCP服务器为AI助手提供访问Snyk安全数据的能力。在您的AI助手（例如Claude Desktop）中进行配置：

启动MCP服务器

# 开发模式（使用ts-node）
npm run mcp-server

# 生产模式（需要先构建）
npm run build
npm run mcp-server:build

测试MCP服务器

使用提供的测试脚本在没有Claude Desktop的情况下测试MCP服务器：

测试get_issues工具：

# 先构建项目
npm run build

# 运行get_issues测试脚本
npx ts-node examples/get-issues.ts [project-id] [status] [severity]

# 示例：
npx ts-node examples/get-issues.ts                                          # 所有开放的问题
npx ts-node examples/get-issues.ts 12345678-1234-1234-1234-123456789012    # 特定项目的开放问题
npx ts-node examples/get-issues.ts 12345678-1234-1234-1234-123456789012 resolved  # 特定项目的已解决问题
npx ts-node examples/get-issues.ts 12345678-1234-1234-1234-123456789012 open critical  # 批评性的开放问题
npx ts-node examples/get-issues.ts "" resolved high                         # 所有已解决的高严重性问题

get-issues.ts脚本接受与get_issues MCP工具相同的参数：

projectId - 项目ID，UUID格式（可选）
status - 问题状态：open、resolved、ignored（可选，默认：open）
severity - 问题严重性：low、medium、high、critical（可选）

测试get_issue工具：

# 获取特定问题的详细信息
npx ts-node examples/get-issue.ts <issue-id>

# 示例：
npx ts-node examples/get-issue.ts 12345678-1234-1234-1234-123456789012

get-issue.ts脚本需要：

issue_id - 要检索的问题的唯一标识符（UUID）（必需）

Claude Desktop配置

添加到您的Claude Desktop配置文件（macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

选项1：使用npx和ts-node（推荐用于开发）

{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "npx",
      "args": [
        "-y",
        "ts-node",
        "/绝对路径到/snyk-mcp-rest/src/mcp-server.ts"
      ],
      "env": {
        "SNYK_API_KEY": "您的snyk-api-key",
        "SNYK_ORG_ID": "您的org-id-uuid",
        "SNYK_ORG_SLUG": "您的org-slug"
      }
    }
  }
}

选项2：使用编译后的JavaScript（推荐用于生产）

首先通过npm run build构建项目，然后：

{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "node",
      "args": [
        "/绝对路径到/snyk-mcp-rest/dist/mcp-server.js"
      ],
      "env": {
        "SNYK_API_KEY": "您的snyk-api-key",
        "SNYK_ORG_ID": "您的org-id-uuid",
        "SNYK_ORG_SLUG": "您的org-slug"
      }
    }
  }
}

重要提示：用实际的绝对路径替换/绝对路径到/snyk-mcp-rest（例如/Users/yourname/Projects/snyk-mcp-rest）。

可用的MCP工具

get_issues - 为组织和项目检索Snyk安全问题
- 参数：
  - projectId（可选）：项目ID，UUID格式（例如"12345678-1234-1234-1234-123456789012"）。
  - status（可选）：按状态过滤（open、resolved、ignored）
  - severity（可选）：按严重性过滤（low、medium、high、critical）
- 配置（通过环境变量）：
  - SNYK_ORG_ID（必需）：Snyk组织ID（UUID）
  - SNYK_ORG_SLUG（必需）：用于URL的组织别名
- 返回：带有直接Snyk URL的格式化问题。除非由专门工具（如get_repo_issues）明确提供，否则repository字段将为null。
注意：projectId参数必须是UUID格式。要找到仓库的项目ID：
```
const projectsApi = new ProjectsApi(config);
const projects = await projectsApi.listOrgProjects({
  version: '2024-11-05',
  orgId: '您的org-id',
  names: ['owner/my-repo']
});
const projectId = projects.data.data?.[0]?.id;
```
get_issue - 检索特定Snyk问题的详细信息
- 参数：
  - issue_id（必需）：要检索的问题的唯一标识符（UUID）
- 配置（通过环境变量）：
  - SNYK_ORG_ID（必需）：Snyk组织ID（UUID）
  - SNYK_ORG_SLUG（必需）：用于URL的组织别名
- 返回：详细的漏洞信息，包括建议修复、补救建议、漏洞详情、升级建议和参考文献

可用的API

客户端提供了对所有Snyk REST API端点的访问：

AccessRequestsApi - 管理访问请求
AppsApi - Snyk应用管理
AuditLogsApi - 审计日志访问
CloudApi - 云安全操作
ContainerImageApi - 容器镜像扫描
CustomBaseImagesApi - 自定义基础镜像管理
FindingsApi - 安全发现
GroupsApi / GroupApi - 组管理
IacSettingsApi - 基础设施即代码设置
InvitesApi - 用户邀请
IssuesApi - 安全问题管理
OrgsApi - 组织操作
PoliciesApi - 策略管理
ProjectsApi - 项目操作
SbomApi - 软件物料清单
ServiceAccountsApi - 服务账户管理
SlackApi / SlackSettingsApi - Slack集成
TargetsApi - 目标管理
TenantsApi - 租户操作
TestsApi - 测试操作
UsersApi - 用户管理

...等等！更多内容请参见src/generated/api/中的完整列表。

开发

运行测试

项目包含全面的测试覆盖：

# 一次性运行所有测试
npm test

# 监视模式（更改时自动重新运行）
npm run test:watch

# 覆盖率报告
npm run test:coverage

# UI模式（交互式测试运行器）
npm run test:ui

测试套件

API客户端测试（tests/api.test.ts）- 配置、API实例化、导出（18个测试）
MCP服务器测试（tests/mcp-server.test.ts）- 问题检索、过滤、分页、项目名称获取（9个测试）
MCP服务器逻辑测试（tests/mcp-server-logic.test.ts）- 处理函数、工具模式（21个测试）
MCP业务逻辑测试（tests/mcp-business-logic.test.ts）- 问题格式化、响应处理（25个测试）
集成测试（tests/integration.test.ts）- 多API工作流、分页处理（7个测试）
错误处理测试（tests/error-handling.test.ts）- HTTP错误、网络故障、验证（8个测试）
索引导出测试（tests/index.test.ts）- 模块导出和类型定义（14个测试）

测试统计：7个测试文件中的102个测试案例，涵盖核心功能、错误场景和边缘情况。

覆盖率：总体代码覆盖率93%以上（src/index.ts为100%，src/mcp-server.ts为93%以上）。根据项目策略，生成的代码（src/generated/**）不计入覆盖率。

项目结构

src/
├── generated/          # 自动生成（不要编辑）
│   ├── api/           # API类
│   ├── models/        # TypeScript接口
│   └── configuration.ts, base.ts, common.ts
├── index.ts           # 主入口点 - API客户端导出
├── mcp-server.ts      # MCP服务器（业务逻辑+启动脚本）
└── tools/             # MCP工具实现
    ├── index.ts       # 工具注册表
    ├── types.ts       # 工具类型定义
    ├── utils.ts       # 共享实用程序
    ├── get-issues.ts  # get_issues工具
    ├── get-issue.ts   # get_issue工具
    ├── get-repo-issues.ts  # get_repo_issues工具
    └── find-projects.ts    # find_projects工具
examples/
├── basic-usage.ts     # 基本API客户端使用示例
├── get-issues.ts      # MCP服务器测试脚本（get_issues工具）
├── get-issue.ts       # MCP服务器测试脚本（get_issue工具）
├── get-repo-issues.ts # MCP服务器测试脚本（get_repo_issues工具）
└── find-projects.ts   # MCP服务器测试脚本（find_projects工具）
tests/
├── api.test.ts                    # API客户端测试（18个测试）
├── mcp-server.test.ts             # MCP服务器集成测试（9个测试）
├── mcp-server-logic.test.ts       # MCP处理函数（21个测试）
├── mcp-business-logic.test.ts     # 问题格式化逻辑（25个测试）
├── integration.test.ts            # 多API工作流（7个测试）
├── error-handling.test.ts         # 错误场景（8个测试）
└── index.test.ts                  # 模块导出（14个测试）
res/
└── snyk-openapi-2025-11-05.json  # OpenAPI规范

重要提示：不要编辑src/generated/中的文件 - 它们是从OpenAPI规范自动生成的。

错误处理

客户端使用Axios进行HTTP操作。适当处理错误：

import { AxiosError } from 'axios';

try {
  const response = await issuesApi.listOrgIssues({
    version: '2024-11-05',
    orgId: '您的org-id'
  });
} catch (error) {
  if (error instanceof AxiosError) {
    console.error('API错误：', error.response?.status);
    console.error('详细信息：', error.response?.data);
  } else {
    console.error('意外错误：', error);
  }
}

环境变量

在项目根目录创建一个.env文件：

SNYK_API_KEY=您的api-key

对于MCP服务器，使用以下环境变量：

SNYK_API_KEY（必需） - 您的Snyk API令牌（从https://app.snyk.io/account获取）
SNYK_ORG_ID（必需） - 您的Snyk组织ID（UUID格式）
SNYK_ORG_SLUG（必需） - 您的Snyk组织别名用于URL（例如my-org）

您可以在Snyk Web UI的组织设置下找到您的组织ID和别名。

版本信息

API版本：使用Snyk REST API版本2024-11-05（所有API调用都需要version参数）
OpenAPI规范：根据snyk-openapi-2025-11-05.json生成
TypeScript：5.9+
Node.js：兼容现代Node.js版本（ES2020目标）

配置

代码生成通过openapitools.json配置：

模板：typescript-axios
单个请求参数：启用
分离模型和API：启用
输出：./src/generated

许可证

MIT

仓库

https://github.com/axelspringer/snyk-mcp-rest

贡献

修改自定义代码（非src/generated/）
如需更新，请修改OpenAPI规范或生成器配置
运行npm test以验证更改
如果添加新功能，请更新此README