# sigsci-mcp-server

MCP server implementation for the Signal Sciences (Fastly NGWAF) API.

日本語版はこちら → [README.ja.md](README.ja.md)

Implements the [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) approach to minimize context consumption from tool definitions.

## Features

- **Progressive Disclosure**: Dynamically discover and load only the tools you need
- **40+ API tools**: Read-only corp/site APIs supported
- **Type-safe**: Fully typed with TypeScript
- **MCP compliant**: Built on the Model Context Protocol SDK

## Usage

### Configure for Cursor / Claude Desktop

- Add to `~/.cursor/mcp.json` or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sigsci-mcp-server": {
      "command": "npx",
      "args": ["-y", "https://github.com/yuki777/sigsci-mcp-server"],
      "env": {
        "SIGSCI_EMAIL": "your-email@example.com",
        "SIGSCI_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Available Tools

### Corp tools

| Tool                             | Description                  |
| -------------------------------- | ---------------------------- |
| `sigsci_list_corps`              | List corporations            |
| `sigsci_get_corp`                | Get corporation details      |
| `sigsci_get_corp_report`         | Get attack report            |
| `sigsci_list_corp_activity`      | List corp activity events    |
| `sigsci_list_corp_users`         | List corp users              |
| `sigsci_get_corp_user`           | Get corp user details        |
| `sigsci_list_corp_rules`         | List corp rules              |
| `sigsci_get_corp_rule`           | Get corp rule details        |
| `sigsci_list_corp_tags`          | List corp signal tags        |
| `sigsci_get_corp_tag`            | Get corp signal tag details  |
| `sigsci_list_corp_lists`         | List corp lists              |
| `sigsci_get_corp_list`           | Get corp list details        |
| `sigsci_list_corp_integrations`  | List corp integrations       |
| `sigsci_get_corp_integration`    | Get corp integration details |
| `sigsci_list_cloudwaf_instances` | List CloudWAF instances      |
| `sigsci_list_cloudwaf_certs`     | List CloudWAF certificates   |

### Site tools

| Tool                               | Description                     |
| ---------------------------------- | ------------------------------- |
| `sigsci_list_sites`                | List sites                      |
| `sigsci_get_site`                  | Get site details                |
| `sigsci_list_site_activity`        | List site activity events       |
| `sigsci_list_site_members`         | List site members               |
| `sigsci_get_site_member`           | Get site member details         |
| `sigsci_list_site_rules`           | List site rules                 |
| `sigsci_get_site_rule`             | Get site rule details           |
| `sigsci_list_templates`            | List rule templates             |
| `sigsci_get_template`              | Get rule template details       |
| `sigsci_list_configured_templates` | List configured templates       |
| `sigsci_get_configured_template`   | Get configured template details |
| `sigsci_list_site_tags`            | List site signal tags           |
| `sigsci_get_site_tag`              | Get site signal tag details     |
| `sigsci_list_site_lists`           | List site lists                 |
| `sigsci_get_site_list`             | Get site list details           |
| `sigsci_list_alerts`               | List alerts                     |
| `sigsci_get_alert`                 | Get alert details               |
| `sigsci_search_requests`           | Search requests                 |
| `sigsci_get_request`               | Get request details             |
| `sigsci_get_request_feed`          | Get request feed                |
| `sigsci_list_events`               | List events                     |
| `sigsci_get_event`                 | Get event details               |
| `sigsci_list_suspicious_ips`       | List suspicious IPs             |
| `sigsci_list_rate_limited_ips`     | List rate-limited IPs           |
| `sigsci_get_whitelist`             | Get whitelist                   |
| `sigsci_get_blacklist`             | Get blacklist                   |
| `sigsci_list_agents`               | List agents                     |
| `sigsci_get_agent`                 | Get agent details               |
| `sigsci_list_top_attacks`          | List top attacks                |
| `sigsci_get_timeseries`            | Get timeseries data             |

### Meta tools (for Progressive Disclosure)

| Tool                          | Description             |
| ----------------------------- | ----------------------- |
| `sigsci_search_tools`         | Search tools by keyword |
| `sigsci_list_tool_categories` | List tools by category  |

## Using Progressive Disclosure

This MCP server implements Anthropic’s recommended [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) approach.

### Problems with traditional MCP

1. **Tool definitions consume context**: Preloading all definitions costs many tokens
2. **Redundant intermediate results**: API responses can flood context as-is

### How this server addresses them

1. **On-demand tool discovery**: Use `sigsci_search_tools` and `sigsci_list_tool_categories` to find only what you need
2. **Control detail level**: `detailLevel` lets you choose name-only/with descriptions/full definitions
3. **Tool definitions as resources**: Access tool definition files as MCP resources

### Example

```typescript
// 1. Check categories first
await sigsci_list_tool_categories({ detailLevel: "name" });

// 2. Search for the needed tools
await sigsci_search_tools({ keyword: "request", detailLevel: "description" });

// 3. Call only the needed tools
await sigsci_search_requests({
  corpName: "my-corp",
  siteName: "my-site",
  q: "tag:XSS",
});
```

## Development

```bash
# Dev mode (watch)
npm run dev

# Build
npm run build

# Lint
npm run lint

# Test
npm test
```

## License

MIT

## References

- [Signal Sciences API Documentation](https://www.fastly.com/documentation/signalsciences/api/)
- [Anthropic: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)