Shannon Lite MCP

Model Context Protocol server for end-to-end Shannon Lite security workflows

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:

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):

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

For Cursor

Add the configuration to your Cursor settings:

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

For Windsurf

Add the configuration to your Windsurf settings:

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

For Warp

Add the following to your Warp session setup:

{
  "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

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

Start a Scan

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

Read Final Report

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

Clean Stop (destructive)

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:

   npm install
   

2. Build the project:

   npm run build
   

3. Run in development mode:

   npm run dev
   

4. Run tests:

   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)
• Model Context Protocol Specification
• MCP 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.