# snyk-mcp-rest

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TypeScript client for the Snyk REST API with built-in Model Context Protocol (MCP) server support. This package provides both a type-safe API client auto-generated from the official Snyk OpenAPI specification and a comprehensive MCP server that exposes **both Snyk CLI tools and REST API tools** for AI assistant integrations.

[Paul Hackenberger](https://www.linkedin.com/in/paul-hackenberger/)

## Architecture

This MCP server provides a **unified interface** to Snyk security scanning through two complementary tool sets:

### 🔧 Snyk CLI Tools (via Proxy)

The server automatically connects to the Snyk CLI and proxies all native CLI commands as MCP tools. These tools provide comprehensive security scanning capabilities:

- **`snyk_test`** - Test projects for vulnerabilities
- **`snyk_code_test`** - Static code analysis for security issues
- **`snyk_container_test`** - Container image scanning
- **`snyk_iac_test`** - Infrastructure as Code scanning
- **`snyk_monitor`** - Monitor projects in Snyk dashboard
- **`snyk_sbom_test`** - SBOM generation and testing
- **`snyk_send_feedback`** - Report security metrics
- **`snyk_trust`**, **`snyk_version`**, and more

### 🌐 REST API Tools (Custom)

Additionally, the server provides custom-built tools using the Snyk REST API for management and querying operations:

- **`snyk_rest_find_projects`** - Search for projects by name
- **`snyk_rest_get_issues`** - Retrieve issues for a project
- **`snyk_rest_get_issue`** - Get detailed issue information
- **`snyk_rest_get_repo_issues`** - Aggregate issues across repository projects

This dual-tool architecture gives AI assistants the best of both worlds: the full power of Snyk CLI for scanning operations, combined with efficient REST API access for querying and management tasks.

## Features

- 🔄 **Auto-generated TypeScript Client** - Generated from official Snyk OpenAPI spec
- 🤖 **MCP Server Integration** - Built-in Model Context Protocol server for AI assistants (Claude, etc.)
- 📦 **Complete Type Safety** - Full TypeScript support with IntelliSense
- 🔌 **Axios-based HTTP Client** - Reliable HTTP operations with error handling
- 🧪 **Comprehensive Testing** - Vitest with coverage support
- 🏗️ **Modular Architecture** - Clean separation between generated and custom code

## Installation

```bash
npm install
```

## Build

The build process includes OpenAPI code generation and TypeScript compilation:

```bash
# Full build (generate + compile)
npm run prepare

# Generate API client from OpenAPI spec
npm run generate

# Compile TypeScript only
npm run build
```

## Usage

### Basic API Client Usage

```typescript
import { Configuration, OrgsApi, IssuesApi } from "snyk-mcp-rest";

// Configure API client
const config = new Configuration({
  apiKey: process.env.SNYK_API_KEY,
  basePath: "https://api.snyk.io/rest",
});

// Or use the helper function
import { createConfiguration } from "snyk-mcp-rest";
const config = createConfiguration(process.env.SNYK_API_KEY!);

// Use Organizations API
const orgsApi = new OrgsApi(config);
const orgs = await orgsApi.listOrgs({
  version: "2024-11-05",
});

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

// Use Projects API to find projects by repository name
const projectsApi = new ProjectsApi(config);
const projects = await projectsApi.listOrgProjects({
  version: "2024-11-05",
  orgId: "your-org-id",
  names: ["owner/my-repo"], // Filter by repository name
});

// Get project IDs from matching repositories
const projectIds = projects.data.data?.map((p) => p.id) || [];

// Fetch issues for specific projects
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 Server Usage

The MCP server provides AI assistants with access to Snyk security data. Configure it in your AI assistant (e.g., Claude Desktop):

#### Starting the MCP Server

```bash
# Development mode (with ts-node)
npm run mcp-server

# Production mode (requires build first)
npm run build
npm run mcp-server:build
```

#### Testing the MCP Server

Test the MCP server without Claude Desktop using the provided test scripts:

**List all available tools:**

```bash
npx ts-node examples/list-tools.ts
```

This will show both Snyk CLI tools and REST API tools.

**Testing REST API tools:**

```bash
# Build the project first
npm run build

# Test snyk_rest_get_issues tool
npx ts-node examples/snyk-rest-get-issues.ts [project-id] [status] [severity]

# Examples:
npx ts-node examples/snyk-rest-get-issues.ts                                          # All open issues
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012    # Open issues for specific project
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012 resolved  # Resolved issues for project
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012 open critical  # Critical open issues
npx ts-node examples/snyk-rest-get-issues.ts "" resolved high                         # All resolved high severity issues
```

The `snyk-rest-get-issues.ts` script accepts the same parameters as the `snyk_rest_get_issues` MCP tool:

- `projectId` - Project ID in UUID format (optional)
- `status` - Issue status: open, resolved, ignored (optional, default: open)
- `severity` - Issue severity: low, medium, high, critical (optional)

**Testing snyk_rest_get_issue tool:**

```bash
# Get detailed information about a specific issue
npx ts-node examples/snyk-rest-get-issue.ts <issue-id>

# Example:
npx ts-node examples/snyk-rest-get-issue.ts 12345678-1234-1234-1234-123456789012
```

The `snyk-rest-get-issue.ts` script requires:

- `issue_id` - The unique identifier (UUID) of the issue to retrieve (required)

#### Claude Desktop Configuration

Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

**Option 1: Using npx with ts-node (recommended for development)**

```json
{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "npx",
      "args": [
        "-y",
        "ts-node",
        "/absolute/path/to/snyk-mcp-rest/src/mcp-server.ts"
      ],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here"
      }
    }
  }
}
```

**Option 2: Using compiled JavaScript (recommended for production)**

Build the project first with `npm run build`, then:

```json
{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "node",
      "args": ["/absolute/path/to/snyk-mcp-rest/dist/mcp-server.js"],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here"
      }
    }
  }
}
```

**Important**: Replace `/absolute/path/to/snyk-mcp-rest` with the actual absolute path to your project directory (e.g., `/Users/yourname/Projects/snyk-mcp-rest`).

#### Available MCP Tools

The MCP server provides two types of tools:

### Snyk CLI Tools

All native Snyk CLI commands are available as MCP tools with the `snyk_` prefix. For a complete list of available CLI tools and their parameters, run:

```bash
npx ts-node examples/list-tools.ts
```

Key CLI tools include:

- **`snyk_test`** - Test projects for open source vulnerabilities
- **`snyk_code_test`** - Static application security testing (SAST)
- **`snyk_container_test`** - Container and Kubernetes security scanning
- **`snyk_iac_test`** - Infrastructure as Code scanning
- **`snyk_monitor`** - Snapshot and continuously monitor projects
- **`snyk_sbom_test`** - Generate and test Software Bill of Materials

Refer to the [official Snyk CLI documentation](https://docs.snyk.io/snyk-cli/commands) for detailed usage of each CLI tool.

### REST API Tools

Custom tools built using the Snyk REST API for querying and management:

- **snyk_rest_find_projects** - Search for Snyk projects by name using the Snyk REST API

  - Parameters:
    - `query` (required): Search query string to match against project names
  - Configuration (via environment variables):
    - `SNYK_ORG_ID` (required): Snyk Organization ID (UUID)
  - Returns: List of projects with their IDs and names

- **snyk_rest_get_issues** - Retrieve Snyk security issues for an organization and project using the Snyk REST API

  - `SNYK_ORG_ID` (required): Snyk Organization ID (UUID)
  - `SNYK_ORG_SLUG` (required): Organization slug for URLs
  - Returns: Formatted issues with direct Snyk URLs. The `repository` field will be `null` unless explicitly provided by specialized tools like `snyk_rest_get_repo_issues`

  **Note**: The `projectId` parameter must be in UUID format. To find the Project ID for a repository:

  ```typescript
  const projectsApi = new ProjectsApi(config);
  const projects = await projectsApi.listOrgProjects({
    version: "2024-11-05",
    orgId: "your-org-id",
    names: ["owner/my-repo"],
  });
  const projectId = projects.data.data?.[0]?.id;
  ```

## Available APIs

The client provides access to all Snyk REST API endpoints:

- **AccessRequestsApi** - Manage access requests
- **AppsApi** - Snyk Apps management
- **AuditLogsApi** - Audit log access
- **CloudApi** - Cloud security operations
- **ContainerImageApi** - Container image scanning
- **CustomBaseImagesApi** - Custom base image management
- **FindingsApi** - Security findings
- **GroupsApi** / **GroupApi** - Group management
- **IacSettingsApi** - Infrastructure as Code settings
- **InvitesApi** - User invitations
- **IssuesApi** - Security issues management
- **OrgsApi** - Organization operations
- **PoliciesApi** - Policy management
- **ProjectsApi** - Project operations
- **SbomApi** - Software Bill of Materials
- **ServiceAccountsApi** - Service account management
- **SlackApi** / **SlackSettingsApi** - Slack integration
- **TargetsApi** - Target management
- **TenantsApi** - Tenant operations
- **TestsApi** - Testing operations
- **UsersApi** - User management

...and many more! See `src/generated/api/` for the complete list.

## Development

### Running Tests

The project includes comprehensive test coverage:

```bash
# Run all tests once
npm test

# Watch mode (auto-rerun on changes)
npm run test:watch

# Coverage report
npm run test:coverage

# UI mode (interactive test runner)
npm run test:ui
```

#### Test Suites

- **API Client Tests** (`tests/api.test.ts`) - Configuration, API instantiation, exports (18 tests)
- **MCP Server Tests** (`tests/mcp-server.test.ts`) - Issue retrieval, filtering, pagination, project name fetching (9 tests)
- **MCP Server Logic Tests** (`tests/mcp-server-logic.test.ts`) - Handler functions, tool schema (21 tests)
- **MCP Business Logic Tests** (`tests/mcp-business-logic.test.ts`) - Issue formatting, response handling (25 tests)
- **Integration Tests** (`tests/integration.test.ts`) - Multi-API workflows, pagination handling (7 tests)
- **Error Handling Tests** (`tests/error-handling.test.ts`) - HTTP errors, network failures, validation (8 tests)
- **Index Exports Tests** (`tests/index.test.ts`) - Module exports and type definitions (14 tests)

**Test Statistics**: 102 test cases across 7 test files covering core functionality, error scenarios, and edge cases.

**Coverage**: 93%+ overall code coverage (100% for `src/index.ts`, 93%+ for `src/mcp-server.ts`). Generated code (`src/generated/**`) is excluded from coverage as per project policy.

### Project Structure

```text
src/
├── generated/          # Auto-generated (DO NOT EDIT)
│   ├── api/           # API classes
│   ├── models/        # TypeScript interfaces
│   └── configuration.ts, base.ts, common.ts
├── index.ts           # Main entry point - API client exports
├── mcp-server.ts      # MCP server (business logic + startup script)
└── tools/             # MCP tool implementations
    ├── index.ts       # Tool registry
    ├── types.ts       # Tool type definitions
    ├── utils.ts       # Shared utilities
    ├── snyk-rest-get-issues.ts  # snyk_rest_get_issues tool
    ├── snyk-rest-get-issue.ts   # snyk_rest_get_issue tool
    ├── snyk-rest-get-repo-issues.ts  # snyk_rest_get_repo_issues tool
    └── snyk-rest-find-projects.ts    # snyk_rest_find_projects tool
examples/
├── basic-usage.ts     # Basic API client usage example
├── snyk-rest-get-issues.ts      # MCP server testing script (snyk_rest_get_issues tool)
├── snyk-rest-get-issue.ts       # MCP server testing script (snyk_rest_get_issue tool)
├── snyk-rest-get-repo-issues.ts # MCP server testing script (snyk_rest_get_repo_issues tool)
└── snyk-rest-find-projects.ts   # MCP server testing script (snyk_rest_find_projects tool)
tests/
├── api.test.ts                    # API client tests (18 tests)
├── mcp-server.test.ts             # MCP server integration tests (9 tests)
├── mcp-server-logic.test.ts       # MCP handler functions (21 tests)
├── mcp-business-logic.test.ts     # Issue formatting logic (25 tests)
├── integration.test.ts            # Multi-API workflows (7 tests)
├── error-handling.test.ts         # Error scenarios (8 tests)
└── index.test.ts                  # Module exports (14 tests)
res/
└── v1-api-spec.yaml  # OpenAPI specification
```

**Important**: Never edit files in `src/generated/` - they are auto-generated from the OpenAPI spec.

## Error Handling

The client uses Axios for HTTP operations. Handle errors appropriately:

```typescript
import { AxiosError } from "axios";

try {
  const response = await issuesApi.listOrgIssues({
    version: "2024-11-05",
    orgId: "your-org-id",
  });
} catch (error) {
  if (error instanceof AxiosError) {
    console.error("API Error:", error.response?.status);
    console.error("Details:", error.response?.data);
  } else {
    console.error("Unexpected error:", error);
  }
}
```

## Environment Variables

Create a `.env` file in the project root:

```env
SNYK_API_KEY=your-api-key-here
```

For the MCP server, these environment variables are used:

- `SNYK_API_KEY` (required) - Your Snyk API token (get from <https://app.snyk.io/account>)
- `SNYK_ORG_ID` (required) - Your Snyk Organization ID (UUID format)
- `SNYK_ORG_SLUG` (required) - Your Snyk Organization slug for URLs (e.g., `my-org`)
- `SNYK_CLI_PROXY_ENABLED` (optional) - Enable/disable Snyk CLI tool proxying (default: `true`)
  - Set to `false`, `0`, or `no` to disable Snyk CLI tools and only use REST API tools
  - When disabled, only custom REST API tools (`snyk_rest_*`) will be available
  - When enabled (default), both Snyk CLI tools and REST API tools are available

You can find your Organization ID and slug in the Snyk web UI under your organization settings.

**Example: Disabling Snyk CLI Proxy**

If you want to use only the REST API tools and disable the Snyk CLI proxy, add this to your `.env` file:

```env
SNYK_CLI_PROXY_ENABLED=false
```

Or set it in your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "node",
      "args": ["/absolute/path/to/snyk-mcp-rest/dist/mcp-server.js"],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here",
        "SNYK_CLI_PROXY_ENABLED": "false"
      }
    }
  }
}
```

## Version Information

- **API Version**: Uses Snyk REST API version `2024-11-05` (all API calls require `version` parameter)
- **OpenAPI Spec**: Generated from `v1-api-spec.yaml`
- **TypeScript**: 5.9+
- **Node.js**: Compatible with modern Node.js versions (ES2020 target)

## Configuration

Code generation is configured via `openapitools.json`:

- Template: `typescript-axios`
- Single request parameter: Enabled
- Separate models and API: Enabled
- Output: `./src/generated`

## License

MIT

## Repository

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

## Contributing

1. Make changes to custom code (not `src/generated/`)
2. Update OpenAPI spec or generator config if needed
3. Run `npm test` to verify changes
4. Update this README if adding new features