Skip to main content
Glama
Cognisn

spindl-workshop

by Cognisn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

spindl-workshop: MCP Response Spooling (CyberCon2026)

Hands-on companion repository for the CyberCon2026 workshop on MCP spooling architecture, built on spindl.

You will run the same simulated firewall MCP server twice, ask it the same security questions, and watch what happens to your client's context window.

  • Exercise 1 (naive mode): the server returns raw dumps. A 1,200 rule rulebase lands in your model's context in full.

  • Exercise 2 (spindl mode): the same server, same data, same tools, with spindl's response spooler enabled. Large results are stored server-side and you explore them with query, aggregate, and distinct tools.

All data is fabricated. The device, vendor, addresses, rules, and logs are fictional and generated deterministically, so everyone in the room sees identical data.

Prerequisites

  • uv installed (uv --version to confirm). uv will fetch a suitable Python (3.10+) automatically if needed.

  • An MCP client that supports local stdio servers. Tested with Claude Desktop, VS Code (Copilot agent mode), and the ChatGPT desktop app. See clients/ for configuration snippets (ChatGPT on the web cannot run local stdio servers; the desktop app can).

  • You should be comfortable editing your client's MCP configuration file.

Related MCP server: MCP-Firewall

Smoke test (do this before the workshop)

uvx --from git+https://github.com/Cognisn/spindl-workshop spindl-workshop --help

If you see the usage text with --mode {naive,spindl}, you are ready.

Exercise 1: the naive server

Configure your client with mode naive (snippets in clients/), then work through exercises/EXERCISE-1.md. You will ask questions such as:

  • Which enabled rules allow inbound RDP from the internet?

  • Which source IP generated the most denies in the last 24 hours?

Watch your client's context/token indicators while you do it.

Exercise 2: the spindl server

Change one word in your client config, naive to spindl, restart the client, and work through exercises/EXERCISE-2.md. Same questions. Note the spool summaries, then let the model drive fw_spooler_query, fw_spooler_aggregate, and fw_spooler_distinct.

What is in the box

Path

Purpose

data/firewall.json

Committed, deterministic fabricated data set

src/spindl_workshop/

The MCP server and its three firewall tools

exercises/

The two hands-on exercise sheets

clients/

Per-client MCP configuration snippets

tools/generate_data.py

Presenter-only data generator (seeded)

The tools exposed

With prefix fw, the server exposes:

  • fw_get_device_info: tiny response, use as a connectivity check

  • fw_get_rulebase: the full security policy (large)

  • fw_get_traffic_logs: 24 hours of traffic logs (very large)

  • fw_list_tools and fw_describe_tool: spindl's built-in skills guides

  • fw_spooler_list / fw_spooler_query / fw_spooler_aggregate / fw_spooler_distinct: present in spindl mode only

For presenters: live token meter

The repo includes a transparent stdio proxy that counts an estimate of the tokens every MCP message contributes to the model's context, without touching the traffic. Point your client at the meter instead of the server:

"args": [
  "--from", "git+https://github.com/Cognisn/spindl-workshop",
  "spindl-workshop-meter", "--mode", "naive"
]

Then, in a terminal beside your client (or on the projector):

uvx --from git+https://github.com/Cognisn/spindl-workshop spindl-workshop-meter watch

The watch display shows a running total and the most recent tool-call responses. Totals carry on across server restarts (clients often relaunch the server when you open a new chat, shown as "server starts") and begin afresh when the mode changes. To zero the counts between rehearsals, run spindl-workshop-meter reset. Counts use the same chars/4 estimate quoted in the exercises; expect the naive rulebase call to meter at roughly 150k tokens (content plus JSON-RPC envelope) against under a thousand in spindl mode. Set SPINDL_METER_LOG to relocate the meter log (default ~/.spindl-workshop/meter.jsonl).

Licence

MIT. Fabricated data, no real systems were harmed.

Available Tools

5 tools
fw_describe_toolB

Get detailed usage guide for a specific tool

NameRequiredDescriptionDefault
tool_nameYesThe full name of the tool to describe (as shown by list_tools)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a safe read-only retrieval, what kind of guide is returned, whether errors occur for unknown tools, or any other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It is concise, though its brevity contributes to gaps in behavioral and contextual detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one required parameter and no output schema, so the description does not need to explain every return detail. Still, it lacks context about what the usage guide contains and how it relates to sibling tools like fw_list_tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single tool_name parameter is well documented in the schema. The description adds no meaning beyond the schema; it merely says 'specific tool,' which aligns with the existing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: get a detailed usage guide for a specific tool. It implicitly contrasts with fw_list_tools by focusing on one named tool, but it does not explicitly name the sibling or clarify the exact distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call this after identifying a tool via fw_list_tools to obtain its guide. However, the description gives no explicit when-to-use, when-not-to-use, or alternative routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fw_get_device_infoA

Return firewall device details (hostname, model, OS, HA state)

NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. 'Return' implies a read-only operation and the field list tells the agent what it gets, but there is no statement about permissions, whether the call is safe/non-mutating, or any rate/HA-specific caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb, resource, and returned fields; nothing wasted and no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully names the returned fields, which is exactly what an agent needs to judge relevance. It falls just short of fully covering behavioral facts (read-only nature, failure modes) that no annotation supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The field list in the description is helpful context but not parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('firewall device details') and enumerates the fields returned (hostname, model, OS, HA state). This is clearly distinct from siblings like fw_get_rulebase and fw_get_traffic_logs, though it never explicitly names those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the tool for basic device identity/status, but the description gives no conditions, prerequisites, or explicit steering away from siblings. For a simple zero-param info tool this is minimally adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fw_get_rulebaseC

Return the full firewall security rulebase

NameRequiredDescriptionDefault
enabled_onlyNoReturn only enabled rules

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, yet it discloses nothing about return volume, pagination, permission requirements, or result ordering for what could be a very large rulebase. The only behavioral cue is the read-like verb 'Return', and 'full' is slightly at odds with the optional filtering parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero waste. Brevity is appropriate, though it leaves the definition thin rather than earning a top score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-optional-parameter read tool with no output schema, the description is minimally adequate. It does not indicate what a rule entry contains or how large the response may be, which matters for an agent deciding whether to filter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the enabled_only parameter and its default are already fully documented in the schema. The description adds no parameter detail and its word 'full' arguably undercuts the filtering option, so it earns only the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb ('Return') and a specific resource ('full firewall security rulebase'), which is readily distinguishable from siblings like fw_get_device_info or fw_get_traffic_logs. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus the sibling tools, no stated prerequisites, and no exclusions. The agent must infer usage purely from the resource name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fw_get_traffic_logsC

Return firewall traffic logs for the last 24 hours

NameRequiredDescriptionDefault
actionNoFilter by action: allow or deny
destination_ipNoFilter by destination IP

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it only states the fixed 24-hour window. It says nothing about permissions required, result size or pagination, whether results are capped, or the shape of a log entry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the 24-hour scope is stated immediately. It is efficient, though brevity here borders on under-specification handled in other dimensions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should describe the return shape (fields per log entry), volume expectations, or truncation behavior. For a read tool that can return large log sets, stating only the time window leaves key details missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both optional filters (action, destination_ip) are fully documented in the schema, so the baseline is 3. The description adds nothing about how the filters combine or whether they are ANDed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Return') plus resource ('firewall traffic logs') and a stated time scope of 24 hours. It is clearly distinguishable from the siblings (device info, rulebase, tool listing), though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus the other fw_* tools, and no mention of prerequisites, expected log volume, or whether the filters are meant to narrow a normally large result set. An agent must infer all of this.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fw_list_toolsA

List all available tools with name, category, and description

NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full disclosure, and it does signal that this is a read-only enumeration returning three named fields. It says nothing about result size, ordering, pagination, or whether tools needing other setup are excluded — relevant for a tool that dumps an entire catalog.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the returned fields appended — no filler, no restatement of the name. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by naming the three fields each entry contains. For a trivial zero-arg lister that is nearly sufficient; only the relationship to fw_describe_tool and output volume are left open.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly adds no parameter text, which is right for a no-arg tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all available tools') and enumerates the fields returned (name, category, description). It implicitly separates itself from fw_describe_tool by being a bulk listing, but never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus fw_describe_tool, which is the obvious alternative for drilling into a single tool. The list-vs-detail distinction is only inferable from the verb, not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.2.2
    • First observedfw_describe_tool
    • First observedfw_get_device_info
    • First observedfw_get_rulebase
    • First observedfw_get_traffic_logs
    • First observedfw_list_tools
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 5 tools

Disambiguation5/5

The three fw_get_* tools each target a clearly distinct resource (device metadata, security rulebase, traffic logs), and the two meta tools split cleanly into index (fw_list_tools) versus detail (fw_describe_tool). No two tools overlap in purpose.

Naming Consistency5/5

Every tool follows the same fw_<verb>_<noun> snake_case convention with a small, predictable verb set (get, list, describe). The shared fw_ prefix further groups all tools under one server namespace.

Tool Count3/5

Five tools is numerically fine, but two of them are introspection/meta tools, leaving only three actual firewall operations. The surface feels thin for a firewall domain, even a read-only workshop one.

Completeness3/5

Read coverage is reasonable but narrow: logs are hard-coded to the last 24 hours with no time-range or filter parameters, and there are no operations for interfaces, zones, NAT, or rule creation/editing. Agents inspecting a firewall will hit dead ends for anything beyond a snapshot.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP-Firewall

    venu1222g
    A
    license
    Not graded
    quality
    C
    maintenance
    A policy and audit layer for Model Context Protocol (MCP). MCP Firewall sits transparently between any MCP client (Claude Desktop, Cursor, VS Code, etc.) and an upstream MCP server, allowing you to inspect, allow, block, or audit requests before they reach the server.
    14 npm
    MIT

  • datalox-gated-runtime

    Oshawott324
    A
    license
    Not graded
    quality
    A
    maintenance
    This MCP server provides a stateful, resettable, verifiable API runtime that gates every tool call, enabling agents to run long workflows against provider-shaped environments without live provider write access. It records decisions, side effects, and outcome evidence for replayable, verifiable benchmark runs.
    Apache 2.0

  • forge-sandbox

    FoundryNet
    A
    license
    Not graded
    quality
    A
    maintenance
    A local, keyless MCP server simulating Forge's industrial telemetry kernel, enabling agents to normalize vendor-specific machine data, forecast breaches, and test integrations against realistic equipment data without credentials or persistence.
    MIT