F
licenseNot graded
qualityD
maintenanceProvides search, detail lookup, and gap listing tools for a security control inventory, enabling natural language queries about control status and gaps.
-
workpapers-mcp
by aminafara123
Click on "Deploy 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., "@workpapers-mcptrace control A3 from risk to test result"
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.
workpapers-mcp
An MCP server over my itgc-audit-workpapers pack: an IT General Controls audit of my own AWS environment, written up as five markdown workpapers. This server exposes that pack as tools any MCP-capable AI client can call.
Audit workpapers are cross-referenced by design. A risk points to a control, the control points to a test, the test points to a finding. Following those links by hand means flipping between files. With this server a model can trace a control from risk to result in one call, or answer "whats still open?" straight from the files.
Tools
Tool | What it does |
| Full text of workpaper 1 to 5 |
| Findings with rating and status, optional rating filter |
| One control traced end to end: matrix row, test procedure and result, findings that cite the test |
| Findings not remediated, tests without a plain Pass, and unfinished drafting placeholders |
Related MCP server: Phantom MCP
Setup
pipx install workpapers-mcpuvx workpapers-mcp works too if you prefer no install. Hacking on a clone instead:
python3 -m venv .venv
.venv/bin/pip install mcpWire it into Claude Code:
claude mcp add workpapers -- workpapers-mcpRunning from a clone, point it at the venv instead:
claude mcp add workpapers -- /path/to/workpapers-mcp/.venv/bin/python /path/to/workpapers-mcp/workpapers_mcp.pyThe server reads the pack from ~/aiProjects/aminWork/automation-portfolio/itgc-audit-workpapers. Point WORKPAPERS_DATA_DIR at your own data folder to read it from somewhere else.
Demo
What it looks like from Claude Code:
> trace control A3 in the workpapers
⏺ workpapers · control_lookup("A3")
A3 (Domain 1: Access)
Risk: Password-only sign-in is phishable
Control: MFA enforced on every human identity
Where it lives: IAM MFA config
Criteria: CIS 1.10
**T-A3 MFA enforcement.**
ToD/ToE: MFA device listing inspected for all 12 demo users.
Result: Exception, see F-2.
Findings citing T-A3: F-2 Two users without MFA
> anything still open?
⏺ workpapers · open_items()
2 open item(s):
- Finding F-2 Two users without MFA: Open
- Test T-A3: Exception, see F-2.
⏺ One real gap. Two users have no MFA, raised as F-2 and still open.
The T-A3 exception is the same issue seen from the test side.The controls and findings above are demo data. The format is exactly what the server returns.
Design notes
Read-only by construction. Every tool reads markdown files. Nothing writes, deletes or touches the network.
Parses the pack as written. Matrix rows, bold test headings and
## F-N.finding sections are the real structure of the workpapers, so the tools follow the same cross-references a reviewer would.Drafting notes stay private. Square bracket
[REVIEW NOTE ...]placeholders are replaced with a neutral marker before any text leaves the server, andopen_itemscounts them so unfinished work still shows up.
Honest notes
The parsing is tied to this pack's markdown conventions. A workpaper written in a different layout wont parse without changes to the regexes.
The pack is a self-audit of one small personal AWS account. The tools make it easier to navigate. They dont add assurance the workpapers dont already carry.
open_itemstreats any finding whose status doesnt start with "Remediated" as open, so accepted and disclosed limitations show up there on purpose.The test lives in
test_server.pyand runs against a synthetic pack in a temp dir. Run it withpython test_server.pyor pytest.
About
Al Amin Bashir Afara, Dubai · github.com/aminafara123 · linkedin.com/in/aminafara
Available Tools
4 toolscontrol_lookupARead-onlyIdempotent
Trace one control end to end: its risk and control row from the matrix, its test procedure and result, and findings that cite it. Accepts A1 or T-A1 style IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| control_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds useful scope by saying it traces the control 'end to end' through risk/control row, test procedure/result, and citing findings, though it does not detail permissions or error behavior.
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?
Two tight sentences: the first states the action and return scope, the second supplies the ID format. No padding, and the core action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with rich annotations and an output schema, the description is complete enough: it explains the control-centric trace and ID formats. Return-value details are already covered by the output schema, so no further elaboration is required.
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 single control_id parameter has 0% schema description coverage, so the description must carry the meaning. It specifies that IDs can be 'A1 or T-A1 style,' which is valuable semantic information beyond the schema's bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource—trace one control—and enumerates the exact related data it returns: risk/control row, test procedure and result, and findings that cite it. It implicitly distinguishes this control-centric trace from siblings like list_findings by scoping everything to a single control.
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 explicit when-to-use guidance or alternative tools are named. The only usage-related hint is the accepted ID format; an agent must infer the tool's place among get_workpaper, list_findings, and open_items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_workpaperARead-onlyIdempotent
Full markdown text of one workpaper, 1 to 5: plan, risk and control matrix, test procedures, findings, management letter.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description's only behavioral addition is the return format (markdown full text), which is modest value beyond the structured fields.
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 no filler; the resource and its payload come first, and the value mapping follows compactly. 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?
An output schema exists, so return-value details need not be restated, and the description still notes the markdown form. The one real gap is the absence of usage/routing guidance, but for a single-parameter read tool this is close to complete.
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?
Schema description coverage is 0% and the sole parameter 'number' has no schema-level documentation, so the description carries the full burden. It compensates well by giving the valid range (1 to 5) and mapping each value to a specific workpaper type, effectively acting as an enum definition.
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 names the exact resource (one workpaper) and the exact payload ('full markdown text'), and enumerates the five workpaper types by number, so the agent knows precisely what it retrieves. It does not explicitly contrast itself with the siblings (list_findings, control_lookup, open_items), but those don't overlap in scope, so confusion risk is low.
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: the description tells the agent what a valid number yields, which suggests it should be called when a specific workpaper's contents are needed. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_findingsBRead-onlyIdempotent
Findings from workpaper 4 with rating and status. Optional rating filter (High, Medium, Low), case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| rating | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that the rating filter is optional and case-insensitive, which is useful behavioral detail, but says nothing about result size, ordering, or pagination.
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?
Two short, front-loaded sentences with no filler. Minor awkwardness in 'Findings from workpaper 4 with rating and status,' which reads like a fragment rather than a stated action.
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?
An output schema exists, so return-value shape need not be explained. For a single-optional-filter read tool with full annotation coverage, the description supplies what is needed to call it correctly, though scope ('workpaper 4') is ambiguous.
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?
Schema description coverage is 0% and the parameter has no enum, so the description carries the burden. It does so reasonably: it enumerates the accepted values (High, Medium, Low) and states matching is case-insensitive, which the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
It names the resource ('findings') and scopes it to 'workpaper 4' with rating and status fields, but there is no verb ('list' is only implied by the name) and the hardcoded workpaper identifier is confusing. It does not differentiate itself from siblings like open_items or get_workpaper.
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 tool versus open_items or get_workpaper, and no mention of prerequisites or scope constraints. The only usage-like statement is that the rating filter is optional, which is inferred from the schema default anyway.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
open_itemsARead-onlyIdempotent
What is not closed yet: findings not remediated, tests without a plain Pass result, and drafting placeholders still in the pack.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable domain semantics by specifying exactly what counts as an 'open item' (unremediated findings, tests without plain Pass, drafting placeholders), which goes beyond the annotations and helps the agent understand the query's scope.
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?
The description is a single, front-loaded sentence that immediately states the tool's purpose and then details the three item types. No unnecessary words or redundancy.
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?
For a parameterless query tool with an output schema and comprehensive annotations, the description provides the essential domain definition of open items. It could be slightly more complete by referencing sibling tools or output ordering, but it covers the core need.
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 no parameters, so parameter semantics are moot. The baseline for zero params is 4, and the description appropriately does not attempt to describe non-existent inputs.
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 clearly defines the tool's scope by enumerating the three categories of open items (unremediated findings, tests without a plain Pass, drafting placeholders). It is a specific query concept, though it does not differentiate itself explicitly from siblings like list_findings or get_workpaper.
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 use this tool versus alternatives. The description states what it returns but does not mention any conditions, prerequisites, or sibling tools that might be more appropriate in certain contexts.
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.
4 tool updates
v1.0.1- First observed
control_lookup - First observed
get_workpaper - First observed
list_findings - First observed
open_items
TDQS
A3.6/5.0
Scored across 4 tools
Disambiguation4/5
Each tool targets a different audit artifact: full workpaper retrieval, findings list, control trace, and open items. list_findings and open_items both surface findings, so slight overlap exists, but descriptions clarify scope.
Naming Consistency3/5
Names use snake_case consistently, but the verb/noun patterns vary: get_workpaper and list_findings are verb_noun, while control_lookup and open_items are noun phrases. Readable but not a single predictable convention.
Tool Count4/5
Four tools for a focused audit-workpaper query server is reasonable; each tool covers a distinct query type. Slightly lean for the domain but not thin enough to be a mismatch.
Completeness4/5
Core read-only audit queries are covered: workpaper text, findings, control tracing, and open items. Missing enumeration/search helpers (e.g., list_workpapers, list controls, free-text search) are minor gaps that an agent can work around by parsing retrieved markdown.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Your audit methodology inside Claude: findings, risks, controls and workpapers in your team format.
Query financial statements, KPIs, ratios, cash forecasts and budgets from your general ledger
Free open dataset of compliance, security and risk AI agents and audit firms. Read-only search.
AI-native GRC: compliance scores, security findings, tickets and agent trust tiers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables authorized compliance verification and security auditing through natural language, bridging AI assistants with industry-standard security tools for enterprise audits.24-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to query and manage a GxP computerized system inventory as a knowledge graph, including blast-radius impact analysis, regulatory lineage, validation-gap detection, audit-trail-compliant status change approvals, and periodic review generation.-
- AlicenseAqualityCmaintenanceEnables AI agents to query SOC 2 and ISO 27001 control evidence with server-enforced authorization, including scoped access, column masking, and audit logging.8MIT