Shannon Lite MCP
Provides runtime status monitoring of Temporal and workers in the Shannon system.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Shannon Lite MCPscan https://example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.tomlScan orchestration (
start,status,workspaces, logs, report reads)Safe destructive operations with explicit confirmation tokens
Smart CLI execution (
shannonbinary or fallback tonpx @keygraph/shannon)TypeScript implementation with strict Zod validation
Related MCP server: Spotter-SAST
Setup
Prerequisites
Node.js 18+
Docker (daemon running)
Shannon CLI access (
shannoninPATHornpxavailable)
MCP Configuration
If you are running this repo locally (unpublished package), build first:
npm install
npm run buildThen 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-mcpornode /path/to/shannon-mcp/dist/index.jsTransport: stdio
Available MCP Tools
shannon_health- Check Docker/Node/CLI readiness, config, and workspace stateshannon_config_set- Write~/.shannon/config.tomlforanthropic,custom_base_url,bedrock,vertex, orroutershannon_config_get- Read current config with secret maskingshannon_start_scan- Start a scan withurl,repo, and optionalconfig,workspace,output,pipeline_testing,routershannon_status- Get Temporal + worker runtime statusshannon_list_workspaces- List known Shannon workspacesshannon_get_workspace- Return detailed workspace/session metadatashannon_read_workflow_log- Read workspaceworkflow.log(tail by default)shannon_read_report- Read final report from workspace deliverablesshannon_stop- Stop Shannon runtime (clean mode requires confirmation token)shannon_uninstall- Remove~/.shannonand 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_stopwithclean=true:I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATAshannon_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
Install dependencies:
npm installBuild the project:
npm run buildRun in development mode:
npm run devRun tests:
npm run test:run
Contributing
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Links
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.
Available Tools
11 toolsshannon_config_getA
Read ~/.shannon/config.toml and return masked credentials and active provider.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explicitly notes that credentials are masked and that the operation reads config, implying safety. It does not mention error handling or file existence, but these are minor given the simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy. Every word adds value, clearly stating action, resource, and outputs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool, the description covers core behavior but lacks output format details (e.g., JSON vs text) and error cases. Given no output schema, more specificity could help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema coverage is 100%. Per rules, baseline is 4. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads '~/.shannon/config.toml' and returns specific outputs ('masked credentials and active provider'), distinguishing it from the sibling 'shannon_config_set'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The context of sibling tools implies a read operation, but the description does not clarify alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_config_setB
Write ~/.shannon/config.toml for Shannon Lite providers (anthropic, custom_base_url, bedrock, vertex, router).
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | Credential provider to configure. | |
| auth_method | No | For anthropic provider only. | |
| api_key | No | ||
| oauth_token | No | ||
| base_url | No | ||
| auth_token | No | ||
| region | No | ||
| token | No | ||
| project_id | No | ||
| key_path | No | ||
| router_default | No | Router default in provider,model format. | |
| openai_key | No | ||
| openrouter_key | No | ||
| model_small | No | ||
| model_medium | No | ||
| model_large | No | ||
| core_max_tokens | No | Optional CLAUDE_CODE_MAX_OUTPUT_TOKENS equivalent. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states it writes a config file without mentioning overwrite/merge behavior, permissions, or side effects. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no wasted words. However, it could be improved with structured formatting for better readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters and no output schema or annotations, the description is too sparse. It fails to provide complete context for correct usage, such as parameter dependencies or return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (24%). The description does not explain the many optional parameters (e.g., token, region, project_id) or their relationships. It adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it writes a config file and lists the supported providers. It clearly differentiates from sibling tools like shannon_config_get (which reads config).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for configuring providers, but does not provide explicit when-to-use or when-not-to-use guidance, nor any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_get_workspaceC
Get detailed data for a single workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Workspace name. | |
| workspaces_dir | No | Optional custom workspace root path. | |
| include_raw_session | No | Include raw session.json payload. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It only says 'Get detailed data', but does not specify read-only nature, performance characteristics, or what constitutes 'detailed data'. Lacks disclosure of side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. However, it is overly brief; additional detail could improve without harming conciseness. Still efficient for a minimal viable description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain the return structure. It only says 'detailed data' without any specifics on fields or format. For a tool with 3 parameters and no output schema, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented in the schema. The description adds no extra meaning beyond 'detailed data'. Baseline 3 is appropriate as the schema handles parameter clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves detailed data for a single workspace, using a specific verb ('Get') and resource ('workspace'). It distinguishes from the sibling 'shannon_list_workspaces' by emphasizing 'single' workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'shannon_list_workspaces'. The description does not mention prerequisites, context, or when not to use it, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_healthA
Check Shannon Lite MCP runtime health (Docker, CLI resolution, config, workspace directory).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It lists the components checked (Docker, CLI, config, workspace), which adds some transparency. However, it does not disclose return format, side effects (likely none), or error handling behavior, leaving the agent partially uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no unnecessary words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool has no parameters and no output schema, the description fails to specify what the tool returns (e.g., boolean, status string, or detailed JSON). This gap reduces an agent's ability to interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is 100%. Baseline is 4. The description adds context beyond the schema by explaining what 'health' entails, which is useful for an agent invoking the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks 'Shannon Lite MCP runtime health' and lists specific aspects (Docker, CLI resolution, config, workspace directory). This verb+resource combination is distinct from sibling tools, which focus on configuration, workspace management, scans, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, context, or cases where another sibling might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_list_workspacesA
List Shannon workspaces and their high-level status.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaces_dir | No | Optional custom workspace root path. | |
| limit | No | Optional max number of workspace rows. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose read-only nature, pagination, or error behavior. 'List' implies non-destructive but no explicit safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb, no unnecessary words. Highly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool with two optional params and no output schema. Could mention return format or that it lists all workspaces, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (workspaces_dir, limit) with descriptions. Description adds no extra meaning beyond schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list', resource 'workspaces', and adds 'high-level status' for specificity. Distinct from siblings like shannon_get_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when listing workspaces, but no explicit when-to-use or when-not-to-use versus siblings like shannon_get_workspace. Context can be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_read_reportB
Read a workspace report file from deliverables (defaults to comprehensive_security_assessment_report.md).
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | ||
| workspaces_dir | No | ||
| filename | No | ||
| max_chars | No | Max characters returned. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It states a read operation (implying non-destructive) and mentions the default filename, but omits error handling, auth needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, directly states purpose and default.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description fails to specify the return format (e.g., file contents as string) or error scenarios. Tool is a data-returning operation with insufficient return information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage, the description adds value by specifying the default filename, but it does not explain workspace, workspaces_dir, or the format of parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('workspace report file from deliverables') with a default filename, distinguishing it from sibling tools like shannon_read_workflow_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., shannon_read_workflow_log for logs). The context lacks explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_read_workflow_logA
Read workflow.log for a workspace (tail by default).
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | ||
| workspaces_dir | No | ||
| bytes | No | Max bytes to return. | |
| from_start | No | When true, read first bytes instead of tail. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that reading is tail-based by default and mentions parameters that affect this behavior (bytes, from_start). However, it does not specify behavior on missing workspaces, error handling, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveys the core purpose and default behavior with no redundancy. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 4 parameters and no output schema, the description covers the primary action and default behavior but omits details on workspaces_dir, return value structure, and error conditions. Adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (bytes and from_start have descriptions). The description adds value by explaining 'tail by default' which relates to from_start, but workspace and workspaces_dir remain undocumented. The implied meaning of workspace is clear, but workspaces_dir lacks explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read workflow.log for a workspace' with a specific verb and resource, and adds the qualifier '(tail by default)' which distinguishes its default behavior from other read tools like shannon_read_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings like shannon_read_report or shannon_status. The description implies log reading but doesn't clarify context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_start_scanC
Start a Shannon Lite scan using URL/repo and optional config/workspace/output/router flags.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Target URL to test. | |
| repo | Yes | Path to source repository. | |
| config | No | Optional YAML config path. | |
| workspace | No | Optional workspace name. | |
| output | No | Optional output directory for deliverables copy. | |
| pipeline_testing | No | ||
| router | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action (start a scan) without mentioning side effects, duration, async behavior, authorization needs, or resource implications. This is insufficient for a tool that likely triggers a long-running process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It directly conveys the core function and mentions the optional parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is too brief. It lacks information about scan lifecycle, return values, error handling, and prerequisites. For a complex tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71%, with descriptions for url, repo, config, workspace, and output. The description lists these as optional flags but adds no new meaning beyond what the schema provides. It does not explain the two boolean parameters (pipeline_testing, router) in detail, just calling them 'flags'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a Shannon Lite scan using URL/repo and optional flags, which is a specific verb+resource. It distinguishes from sibling tools like shannon_status or shannon_stop by focusing on starting a scan, though it could be more precise about the scan type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like shannon_status or shannon_read_report. It does not specify prerequisites, context, or exclusions, leaving the agent without decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_statusB
Get Shannon runtime status (Temporal + workers).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Get Shannon runtime status' without disclosing what is returned, side effects, or any behavioral traits beyond the basic intent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is very minimal. It does not explain what 'runtime status' includes, such as formats or fields, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100%, so the description does not need to add parameter information. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Shannon runtime status (Temporal + workers)', which is specific and distinguishes it from sibling tools like 'shannon_health' or 'shannon_stop'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as 'shannon_health' which might have overlapping functionality. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_stopA
Stop Shannon worker and infra containers. Clean mode requires a confirmation token.
| Name | Required | Description | Default |
|---|---|---|---|
| clean | No | Also remove Shannon volumes/network. | |
| confirm_destructive | No | Required for clean mode: I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATA |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral context. It only mentions stopping containers and a destructive clean mode, but lacks details on permissions, impact on running processes, or atomicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the main action and immediately address the dependent parameter requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward stop action, the description covers the core functionality and clean mode caveat, though it omits whether the stop is forceful or graceful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are documented in the schema with descriptions; the description adds no new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Stop' and the resource 'Shannon worker and infra containers', precisely distinguishing it from sibling tools that deal with configuration, health, status, or starting scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage for stopping, but provides no explicit guidance on when to choose this tool over alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shannon_uninstallA
Stop Shannon runtime and remove ~/.shannon. Requires explicit confirmation token.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm_destructive | Yes | Required token: DELETE_SHANNON_HOME_AND_STOP_SHANNON | |
| clean | No | Also remove Shannon volumes/network while stopping. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description explicitly states the destructive action (stop runtime and remove home directory) and mentions the confirmation token. Lacks details on how 'clean' affects volumes/network and post-uninstall state, but adequately discloses core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no unnecessary words. Information is front-loaded: action, target, precondition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the main purpose and prerequisites. It could mention expected outcome or return format, but for a destructive uninstall tool, the current level is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds little beyond what the schema already provides. It reinforces the confirmation token requirement, but that is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Stop' and resource 'Shannon runtime' and 'remove ~/.shannon'. It distinguishes from siblings like shannon_stop which likely only stops without removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like shannon_stop. The only hint is the requirement for a confirmation token, which is not a usage context but a precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool has a clearly distinct purpose: config, workspace management, health, scan execution, report reading, runtime control, and uninstall. No overlapping functionality.
All tools follow the consistent pattern `shannon_<verb>` or `shannon_<verb>_<noun>` (e.g., shannon_config_get, shannon_list_workspaces, shannon_start_scan, shannon_stop).
11 tools cover the essential operations for managing Shannon Lite without being excessive. The scope is well-defined for typical use cases.
Core workflows are covered: config, workspace listing, scan initiation, report reading, health checks, stop, and uninstall. Minor gaps exist (no explicit workspace creation or scan status polling), but agents can work around them.
Maintenance
Related MCP Connectors
MCP server for ScanMalware.com URL scanning, malware detection, and analysis.
Authenticated MCP server for ClearPolicy policy and compliance workflows.
Scans remote MCP servers for protocol, security, and TLS issues; exposes scan tools via MCP.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnterprise-grade MCP server for static application security testing with multi-tool integration, compliance verification, AI-powered remediation, and multi-tenant management.2310MIT
- FlicenseNot gradedqualityDmaintenanceA remote MCP server that exposes mock application security testing data (applications, scans, issues) for LLM clients to query security posture using natural language.
- AlicenseNot gradedqualityCmaintenanceMCP server for ai-scanner that enables AI agents to scan codebases for LLM usage, AI frameworks, and exposed secrets.701MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/devinoldenburg/shannon-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server