<h1 align="center">Shannon Lite MCP</h1>

<p align="center">
  <strong>Model Context Protocol server for end-to-end Shannon Lite security workflows</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/shannon-lite-mcp"><img src="https://img.shields.io/npm/v/shannon-lite-mcp" alt="NPM Version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
  <a href="https://github.com/devinoldenburg/shannon-mcp/actions/workflows/ci.yml"><img src="https://github.com/devinoldenburg/shannon-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2" alt="MCP Compatible"></a>
</p>

This package enables AI assistants and applications to configure Shannon, start scans, monitor runtime, inspect workspaces, and read reports programmatically.

## Features

- Full Shannon Lite workflow support through MCP tools
- Built-in config management for `~/.shannon/config.toml`
- Scan orchestration (`start`, `status`, `workspaces`, logs, report reads)
- Safe destructive operations with explicit confirmation tokens
- Smart CLI execution (`shannon` binary or fallback to `npx @keygraph/shannon`)
- TypeScript implementation with strict Zod validation

## Setup

### Prerequisites

- Node.js 18+
- Docker (daemon running)
- Shannon CLI access (`shannon` in `PATH` or `npx` available)

### MCP Configuration

If you are running this repo locally (unpublished package), build first:

```bash
npm install
npm run build
```

Then use command `node` with args `[/absolute/path/to/shannon-mcp/dist/index.js]` in your MCP client configuration.

#### For Claude Desktop

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

```json
{
  "mcpServers": {
    "shannon-lite": {
      "command": "npx",
      "args": ["-y", "shannon-lite-mcp"]
    }
  }
}
```

#### For Cursor

Add the configuration to your Cursor settings:

```json
{
  "mcpServers": {
    "shannon-lite": {
      "command": "npx",
      "args": ["-y", "shannon-lite-mcp"]
    }
  }
}
```

#### For Windsurf

Add the configuration to your Windsurf settings:

```json
{
  "mcpServers": {
    "shannon-lite": {
      "command": "npx",
      "args": ["-y", "shannon-lite-mcp"]
    }
  }
}
```

#### For Warp

Add the following to your Warp session setup:

```json
{
  "shannon-lite": {
    "command": "npx",
    "args": ["-y", "shannon-lite-mcp"],
    "working_directory": null,
    "start_on_launch": true
  }
}
```

#### For Other MCP Clients

Use standard MCP server settings:

- **Command**: `npx -y shannon-lite-mcp` or `node /path/to/shannon-mcp/dist/index.js`
- **Transport**: stdio

## Available MCP Tools

- `shannon_health` - Check Docker/Node/CLI readiness, config, and workspace state
- `shannon_config_set` - Write `~/.shannon/config.toml` for `anthropic`, `custom_base_url`, `bedrock`, `vertex`, or `router`
- `shannon_config_get` - Read current config with secret masking
- `shannon_start_scan` - Start a scan with `url`, `repo`, and optional `config`, `workspace`, `output`, `pipeline_testing`, `router`
- `shannon_status` - Get Temporal + worker runtime status
- `shannon_list_workspaces` - List known Shannon workspaces
- `shannon_get_workspace` - Return detailed workspace/session metadata
- `shannon_read_workflow_log` - Read workspace `workflow.log` (tail by default)
- `shannon_read_report` - Read final report from workspace deliverables
- `shannon_stop` - Stop Shannon runtime (clean mode requires confirmation token)
- `shannon_uninstall` - Remove `~/.shannon` and stop runtime (requires confirmation token)

## Safety Notice

Shannon Lite can run real security test flows. Use only on systems you are authorized to test.

Destructive operations require exact confirmation tokens:

- `shannon_stop` with `clean=true`: `I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATA`
- `shannon_uninstall`: `DELETE_SHANNON_HOME_AND_STOP_SHANNON`

## Usage Examples

### Configure Anthropic API Key

```javascript
await mcp.callTool("shannon_config_set", {
  provider: "anthropic",
  auth_method: "api_key",
  api_key: "sk-ant-..."
});
```

### Start a Scan

```javascript
await mcp.callTool("shannon_start_scan", {
  url: "https://example.com",
  repo: "/absolute/path/to/repo",
  workspace: "q2-audit"
});
```

### Read Final Report

```javascript
await mcp.callTool("shannon_read_report", {
  workspace: "q2-audit"
});
```

### Clean Stop (destructive)

```javascript
await mcp.callTool("shannon_stop", {
  clean: true,
  confirm_destructive: "I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATA"
});
```

## Development Setup

### Prerequisites

- Node.js 18+
- npm

### Local Development

1. **Install dependencies**:

   ```bash
   npm install
   ```

2. **Build the project**:

   ```bash
   npm run build
   ```

3. **Run in development mode**:

   ```bash
   npm run dev
   ```

4. **Run tests**:

   ```bash
   npm run test:run
   ```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the `LICENSE` file for details.

## Links

- [Shannon (Keygraph)](https://github.com/KeygraphHQ/shannon)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

## Support

- Create an issue for bug reports or feature requests
- Check existing issues before creating new ones
- Include reproduction steps, environment info, and relevant logs

---

Made with care for the security engineering community.