knowject-mcp-tool-designer

name

knowject-mcp-tool-designer

description

Use when the user wants to design MCP tool candidates, function/tool calling schemas, or agent tool risk gates from project API surfaces. Triggers on phrases like "/knowject mcp tools", "design MCP tools from this API", "把这些 endpoint 设计成 MCP tools", "为 agent 工具加确认 gate", "API-to-MCP tool design", or "which endpoints are safe for tool calling". Day-1 output is design artifacts only under knowject/tools/: README.md, mcp-tools.plan.md, mcp-tools.schema.json, and tool-risk-report.md. It does not implement an MCP server or runtime tool handlers.

knowject-mcp-tool-designer

You design MCP tool candidates from project API surfaces. The output is a conservative, reviewable set of design artifacts that map endpoints to tool names, input schemas, risk labels, confirmation gates, auth notes, audit notes, and rollback notes.

Hard rules

1. Refuse without knowject/context.yaml, unless the user only asks for a dry-run explanation of the Skill. Point at knowject-context-init and stop.
2. Design artifacts only in Day 1. Do not implement an MCP server, runtime handlers, tool registration code, platform APIs, UI, auth logic, or permission checks.
3. Never call external APIs or project endpoints. Read API descriptions, inventories, and source files only.
4. Never copy secrets or environment values. Do not read or copy .env*, tokens, keys, passwords, cookies, auth headers, DB URLs, base URLs, private credentials, or raw sensitive records.
5. Every tool candidate must cite its source endpoint. Use a method/path plus source file, OpenAPI operation, endpoint inventory entry, or explicit user-provided endpoint.
6. Risk labels are required. Every candidate must use one of read_only, low_write, destructive, external_side_effect, or sensitive_data.
7. Confirmation gates are required for destructive operations, external side effects, sensitive data access, and bulk operations. If uncertain, require confirmation.
8. Diff before write; confirm before write. Show unified diffs for knowject/tools/README.md, mcp-tools.plan.md, mcp-tools.schema.json, and tool-risk-report.md; write only after explicit user confirmation.
9. Use the user's language for chat replies and Markdown summaries; JSON keys and enum values stay English.

Flow

Step 1 - Verify preconditions

Confirm the current directory is the target repo root:

git rev-parse --show-toplevel

Read knowject/context.yaml.

• If it is missing and the user wants tool designs: refuse, point at knowject-context-init, and stop.
• If it is missing and the user asks only how the Skill works: explain the output contract and stop before reading API sources.
• Use api.sources and optional api.client when present.

Step 2 - Pick input mode

Supported Day-1 input modes:

Mode	Use when
context-openapi	knowject/context.yaml#api.sources[*].format is openapi.
context-express	api.sources[*].format is express.
endpoint-inventory	The user provides output from knowject-read-api.
explicit-endpoints	The user provides a list of method/path endpoints.

If api.sources is missing or unsupported, ask for an endpoint inventory or explicit endpoint list. Do not guess endpoints.

Step 3 - Build or read endpoint inventory

Apply references/api-selection.md.

Preferred source order:

1. Existing endpoint inventory generated by knowject-read-api.
2. OpenAPI source from context.yaml.
3. Express route source from context.yaml.
4. Explicit user-provided endpoint list.

When source format is supported by knowject-read-api, prefer its deterministic extractors and inventory shape. Do not change knowject-read-api behavior.

Step 4 - Select tool candidates

For each candidate endpoint:

• Prefer narrow, task-oriented read endpoints before write endpoints.
• Exclude endpoints whose behavior is unclear.
• Exclude auth/session, internal admin, raw import/export, and dangerous bulk endpoints unless the user explicitly asks to evaluate them.
• Keep read and write candidates separated in the plan.
• Attach a source endpoint citation before writing the candidate.

Step 5 - Assign schema, risk, and gates

Use references/tool-risk-taxonomy.md.

Each candidate must include:

• tool_name
• description
• source_endpoint
• input_schema
• output_shape_notes
• risk_level
• requires_confirmation
• auth_scope_notes
• audit_log_notes
• rollback_notes

Set requires_confirmation: true when:

• the endpoint deletes, updates, sends, imports, exports, purchases, provisions, or triggers irreversible work
• the endpoint can affect external systems
• the endpoint can expose sensitive data
• the endpoint supports bulk operations
• the risk is uncertain

Step 6 - Prepare files

Apply references/mcp-tool-design-contract.md.

Write or update exactly these Day-1 files:

knowject/tools/
  README.md
  mcp-tools.plan.md
  mcp-tools.schema.json
  tool-risk-report.md

Step 7 - Diff and confirm

Before writing:

1. Validate mcp-tools.schema.json parses as JSON.
2. Show unified diffs for every create or update.
3. Ask: "Apply these MCP tool design artifacts? (yes / cancel)".
4. On yes, write the files.
5. On cancel, stop without writing anything.

Step 8 - Summarize

After writing, report:

• Tool candidates added or updated.
• Risk levels used.
• Confirmation gates required.
• Endpoints skipped, with reason.
• Any sensitive source intentionally not copied.
• Clear reminder that no MCP server or runtime handler was implemented.

Failure modes

• knowject/context.yaml missing: refuse and tell the user to run knowject-context-init first.
• No API sources or endpoints found: ask for a knowject-read-api inventory or explicit endpoint list.
• Unsupported source format: explain supported Day-1 modes and ask for OpenAPI, Express, inventory, or explicit endpoints.
• Endpoint behavior unclear: skip it or mark it high-risk with confirmation required; do not invent behavior.
• Sensitive or secret-bearing source: skip sensitive values and warn the user.
• Schema JSON invalid: fix before showing the write confirmation.
• User does not confirm the diff: stop without writing.

What this Skill does NOT do

• Does not implement an MCP server.
• Does not create runtime tool handlers or register tools in an agent runtime.
• Does not call external APIs or project endpoints.
• Does not modify app API routes, auth/permission code, platform UI, or backend services.
• Does not change knowject-read-api behavior.
• Does not claim that the designed tools are safe to run without implementation review, tests, auth checks, and audit integration.

See also

• Risk taxonomy: references/tool-risk-taxonomy.md
• File contract: references/mcp-tool-design-contract.md
• API selection: references/api-selection.md
• Examples: references/examples/
• API discovery: ../knowject-read-api/SKILL.md
• API typing: ../knowject-api-to-types/SKILL.md
• Schema reference: ../_shared/context-yaml-schema.md