gofastr-mcp-debug
Skill24 starsChanged yesterdayMITView on GitHub
Live debug a running GoFastr app via its MCP endpoint, the combined entry point covering both the log_* tools (battery/log) and the app_* introspection tools (framework). Use when the user wants to "debug the live app", "see what's going on right now", "tell me about the running server", or any general "go look at the running app" prompt.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-uiSkill
- log-debugSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 93
All tool calls are POST /mcp with body:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug a running GoFastr app live (one-page guide)
This skill is the starting point for any agent investigation of a running GoFastr app via MCP. For deep recipes, jump to:
.claude/skills/log-debug/SKILL.mdcovers the fourlog_*tools (recent entries, structured filter, metrics, level mutation)..claude/skills/app-introspect/SKILL.mdcovers the nine introspection tools (app_routes,app_plugins,app_batteries,app_modules,app_config,app_readiness,app_goroutine_leaks,app_routines,app_unmounted), theframework_docs_list/framework_docs_get/framework_docs_searchtools an app adds withframework.WithMCPTools(mcptools.Register)for the embedded framework docs, andcontracts_list/contracts_explain/contracts_capabilitiesfor the rulesgofastr verifyenforces. Undergofastr devonly,contracts_verifyruns those rules against the app's source andcontracts_fixapplies one rule's autofixes; both touch local files, so a deployed app does not register them.
When to use which
| User asks… | Reach for |
| "What just happened?" / "Why is X failing?" | log_recent, log_filter (log-debug) |
| "Trace request ID abc-123" | log_filter with request_id + historical=true |
| "Is the app ready?" | app_readiness (app-introspect) |
| "What endpoints exist?" | app_routes (app-introspect) |
| "What plugins / batteries are loaded?" | app_plugins, app_batteries (app-introspect) |
| "What modules are enabled?" | app_modules (app-introspect) |
| "Did my routine body change propagate?" | app_routines (app-introspect); ledger_state=drifted flags it |
| "Which framework packages did we unmount?" | app_unmounted (app-introspect) |
| "Is anything leaking goroutines?" | app_goroutine_leaks (app-introspect) |
| "Turn module X off / back on" | app_module_disable, app_module_enable (mutating) |
| "How does framework feature X work?" | framework_docs_search → framework_docs_get |
"Why did gofastr verify flag this?" | contracts_explain: the rule's why, fix, and example |
| "What does the framework require of me?" | contracts_capabilities → contracts_list |
| "What's wrong with this app's code?" | contracts_verify (dev loop), then contracts_explain per rule |
| "Fix the GOFASTR#### findings for me" | contracts_fix (dev loop, WRITES), one rule at a time |
| "Are the logs even working?" | log_metrics: non-zero counters = lost entries |
| "Crank up DEBUG for 30 seconds, then back" | log_set_level DEBUG (save .previous_level) → reproduce → log_set_level <previous_level> |
Getting started
Under gofastr dev, everything below is automatic: the framework
auto-mounts /mcp and enables introspection + control, every
CRUD-enabled entity serves its {entity}_* data tools (no mcp: true
needed), and battery/log (if registered) auto-enables its log_*
tools. Opt-out: GOFASTR_DEV_MCP=0. The one exception is the
framework_docs_* set: the dev loop never implies it, the app passes
framework.WithMCPTools(mcptools.Register) (generated apps do). So for a
dev-loop app there is nothing else to wire; just connect.
Outside the dev loop, the app opts in explicitly:
fwApp := framework.NewApp(
framework.WithConfig(framework.AppConfig{Name: "<your-app>"}), // battery/log needs a non-empty app name for its state dir
framework.WithMCP(), // mounts /mcp (POST + GET SSE) + discovery wellknowns
framework.WithMCPIntrospection(), // app_* tools (read-only)
framework.WithMCPTools(mcptools.Register), // framework_docs_* tools (framework/docs/mcptools)
framework.WithMCPControl(), // app_module_enable/disable (mutating; trusted /mcp only)
)
fwApp.RegisterPlugin(log.New(log.Config{
EnableMCP: true, // log_recent, log_filter, log_metrics (read-only)
AllowMCPMutation: true, // also registers log_set_level (mutating; trusted /mcp only)
MCPRingSize: 2000,
}))(WithMCP() replaces hand-mounting /mcp; doing both panics with a
route conflict.) examples/site and generated apps already
have WithMCP + WithMCPIntrospection + framework.WithMCPTools(mcptools.Register) + the log battery wired. Spin
the site up with the repo's normal dev workflow:
./scripts/dev-watch.sh # examples/site on :8082, auto-rebuild, log_* tools on
# or
GOFASTR_DEV=1 go run ./examples/site # :8083; plain `go run` exposes introspection but NOT log_* (dev-only)Then point curl at http://localhost:8082/mcp (or :8083 for the
GOFASTR_DEV=1 form) and use the log-debug + app-introspect skills'
recipes.
The JSON-RPC envelope
All tool calls are POST /mcp with body:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "<tool_name>",
"arguments": { ... }
}
}Response wraps the tool's return value as a JSON-encoded string in
.result.content[0].text. Pipe through jq -r '.result.content[0].text' | jq .
to get back to structured JSON. List available tools via
"method": "tools/list" (no params).
Anti-patterns
- Don't reach for MCP when grepping the file directly is easier. If
the user knows exactly what they're looking for and has shell access,
tail -f ~/.local/state/<app>/server.log | grep …may be the right move (Linux honors$XDG_STATE_HOMEbefore~/.local/state). MCP wins when the agent (not the user) is the consumer. - Don't curl tools you don't know the shape of.
tools/listfirst if you're not sure what's registered; the descriptions are written for agents. - Don't forget to revert state mutations. The mutating tools are
log_set_level, plus (whenWithMCPControl()is wired)app_module_enable/app_module_disable. Treat each like a temporary debug toggle: flip on, reproduce, flip back. Captureprevious_levelfromlog_set_levelso you restore what was actually there, not a hard-coded INFO.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

