Experimental · v2.0.0

MCP Tool Spec Writer

Turns a plain-language tool idea into something an agent can ingest: tool name, description, JSON schema for params, error codes, example calls, and a short AI-docs block. Warns on dangerous defaults (unscoped file writes, shell, unbounded fetch). Spec-sheet layout. For people wiring tools who would rather find the footgun on paper.

night.shift · 1,421 votes · 8,560 score · 4,297 opens

#mcp#tools#schema#safety

Spec

Build an MCP Tool Spec Writer — a spec sheet for a single tool, not an IDE.

PRODUCT
Input: what the tool should do, what it must never do, and the runtime it talks to (fs, http, db, shell, other). Output a complete tool spec an agent can be handed.

SPEC SHEET (fixed sections)
- Name: snake_case, ≤32 chars, generated then editable
- Description: 1–3 sentences, imperative, no marketing
- When to use / when not to use
- Params: JSON Schema draft-07 object. Every property has type, description, and whether required. No “any”.
- Returns: shape in prose + a JSON example
- Errors: 4–8 codes (NOT_FOUND, DENIED, INVALID, TIMEOUT, …) with what the agent should do next
- Examples: 2 calls (happy, and a denied/invalid)
- AI-docs: a 10–20 line block meant to be pasted into a system prompt
- Danger: a checklist. If runtime is shell or fs-write, default to DANGER and require an allowlist field in the schema (paths or commands). If the user tries to omit it, block export with “unscoped writes/shell will not export”.

SCREENS
1. Intent form
2. Spec sheet (editable fields)
3. Export — copy JSON schema, copy AI-docs, copy the whole markdown spec

DATA
Last 8 tools, localStorage.

EMPTY
Sample intent: “read a file under /workspace, never above it”.

VISUAL
Spec sheet. Schema in a mono pane, validated enough to reject trailing commas. Danger is a rule-left section, not a red rainbow.

OUT OF SCOPE
Generating the tool implementation, hosting an MCP server, OAuth to a runtime.

ACCEPTANCE
- Sample export includes an allowlist path param.
- Shell runtime without allowlist cannot export.
- JSON schema is copyable and parseable (no comments).
- Mobile: sections stack; copy buttons 44px.