ffc-dev-mcp-tool
Skill16 starsChanged 37 days agoMITView on GitHub
Add or change an MCP tool, or touch the MCP server internals, in the ffc Go codebase - toolHandler and the argument helpers, toolActions and toolSurface registration, scopeOf and the per-site policy, confirmations, multi-DocType results filtered with policyFrom, result size caps, jq, tool sets, instructions, resources and prompts, the detached HTTP daemon, multi-site serving, and ffc mcp install/uninstall (internal/mcpinstall). Use it whenever you edit internal/cmd/mcp_*.go or internal/mcpinstall, or expose a CLI feature to AI clients. Load ffc-dev first.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- desktop/CLAUDE.mdCLAUDE.md
- ffc-bulk-lifecycleSkill
- ffc-coreSkill
- ffc-dev-clientSkill
- ffc-dev-commandSkill
- ffc-dev-desktopSkill
- ffc-devSkill
- ffc-dev-testingSkill
- ffc-files-collabSkill
- ffc-mcpSkill
- ffc-reports-apiSkill
- ffc-setupSkill
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 29
Surface: if the instructions (mcpInstructions) or a prompt should mention the tool, gate the line on has(tool).
≈ “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
Add or change an MCP tool
The mcp command is a long-running server, not a one-shot command. CLAUDE.md pitfalls "MCP policy", "MCP confirmation", "Multi-site MCP", "MCP surface" and "ffc mcp install" are the full rules.
Hard rules
- stdout is the JSON-RPC channel. A handler never writes to stdout and never calls
output.Print*. stderr is the client's log in stdio mode andmcp.logwhen detached: never print secrets there. - Errors become tool errors (
mcp.NewToolResultError, nil Go error). A non-nil Go error from a handler is a protocol crash; reserve it for the unexpected.toolHandleralready does this for you. - Read JSON-valued arguments with
jsonArg/rawJSONArg/objectArg(native JSON or a JSON string), lists withstringsArg/listArg, integers withintArg, optional strings withstringArg. Neverreq.GetStringfor a JSON parameter: it returns "" for a native object and silently drops filters.req.RequireStringis fine for plain required strings. - The site client comes from the env (
toolHandler→env.client), which goes throughloadSite/newSiteClient. Never build one yourself. - MCP never dry-runs.
Checklist for a new tool
- Define it in the right file (
mcp_tools.gocore,mcp_lifecycle_tools.go,mcp_collab_tools.go,mcp_files_tools.go,mcp_identity_tools.go, ...):mcp.NewTool(name, mcp.WithDescription(...), mcp.WithReadOnlyHintAnnotation(...), params...), ordocTool(name, desc, readOnly, destructive, extra...)for a tool on one document (addsdoctype*,name*and the annotations). JSON parameters usejsonParam(name, desc)(no fixed schema type). - Handler:
s.AddTool(tool, toolHandler(env, func(req mcp.CallToolRequest) (toolCall, error) { ...parse and validate...; return func(ctx, c) (interface{}, error) {...}, nil })). Validate everything in the parse step so a bad call costs no login or request. Reuse the CLI's shared function (ascheckPermission,runSearch,fetchDocContext,buildAggregateQueryare shared) instead of duplicating logic. - Register the function in
registerAllTools(mcp_tools.go). toolActions(mcp_policy.go):actRead,actWriteoractMethod, matching the read-only annotation.TestMCPPolicyCoversEveryToolfails otherwise.toolSurface: tool set (core,lifecycle,collab,admin,files,erp), title, andbigwhen the result can approach 512 KiB (big read tools also get thejqargument).TestMCPToolSurfacefails otherwise.collab,admin,files,erpare off by default.scopeOf: teach it every argument other thandoctype/namethat names a DocType, document, method or report. If the tool writes another DocType as a side effect (Comment, ToDo, DocShare, File), add it tocollabDoctypesso DocType rules and the sensitive list apply.- Confirmation: a tool that destroys, merges or widens access goes in
needsConfirm, with aconfirmMessageand acliEquivalentcase. - Results spanning DocTypes the call does not name (global search hits, linked documents): filter inside the toolCall with
policyFrom(ctx), fail when it returnsok == false(the zero policy allows everything), and report what was dropped ashidden_by_policy. - Size: return plain values;
toolHandlermarshals them throughmarshalResult(512 KiB cap). A row list that can grow uses thefitListRows/fitReportRowspattern (largest prefix plustruncated,hint). A tool with an output schema returnsstructuredOut{Text, Structured}and keeps its text byte-identical. - Surface: if the instructions (
mcpInstructions) or a prompt should mention the tool, gate the line onhas(tool). - Sites: the
siteargument is added for free when several sites are served. A tool about the server rather than a site goes insiteless. - Tests:
newMCPFake(t, readOnly)+callTool(t, s, name, args)(goes through JSON-RPC decoding); confirmation flows withmcpTClient. Cover policy refusal (nothing sent), read-only registration, and argument decoding of native vs string JSON. - Docs: CLAUDE.md, docs/mcp/tools.md, and
skills/ffc-mcp/references/tools.md.
Skeleton:
func registerThing(s *server.MCPServer, env *mcpEnv) {
tool := mcp.NewTool("thing",
mcp.WithDescription("What it does, what it returns, when to use it instead of X."),
mcp.WithReadOnlyHintAnnotation(true),
mcp.WithOpenWorldHintAnnotation(true),
mcp.WithString("doctype", mcp.Required(), mcp.Description("The Frappe DocType")),
jsonParam("filters", `Filter as a JSON object or array`),
mcp.WithNumber("limit", mcp.Description("Maximum rows. Default 20.")),
)
s.AddTool(tool, toolHandler(env, func(req mcp.CallToolRequest) (toolCall, error) {
doctype, err := req.RequireString("doctype")
if err != nil {
return nil, err
}
filters, err := rawJSONArg(req, "filters")
if err != nil {
return nil, err
}
limit, err := intArg(req, "limit", 20)
if err != nil {
return nil, err
}
return func(ctx context.Context, c *client.FrappeClient) (interface{}, error) {
return c.GetList(ctx, doctype, client.ListOptions{Filters: filters, Limit: limit})
}, nil
}))
}How a call flows
toolHandler: parse → site (env.site, re-read every call, so policy edits apply at once) → scopeOf → policy.check (refusal: policy: ..., nothing sent) → policy.confirm (elicitation) → client → call → one audit line in mcp-audit.jsonl (args redacted via client.RedactArgs). Resources (ffc://...) are served by calling the tool's own handler (resourceReader), never a separate client path.
Server internals (daemon, multi-site, confirmation state, jq child process, surface, mcp install): references/server-internals.md.
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.

