rahmanef63/mso/mso-mcp-feature-engineering

/mso-mcp-feature-engineering — MCP Feature Engineering

Use this skill for a durable MSO MCP implementation or repair. The detailed checklist lives in `docs/MCP-FEATURE-IMPLEMENTATION.md`.

Trigger and boundaries

• Use when: adding, removing, renaming, debugging, or extending an MCP tool; changing

OAuth/scope/audit/toolset behavior; adding trusted skill discovery/routing; or adding an opt-in project function capability.

• Do not use when: answering a one-off MCP question, performing one direct bounded read, or

changing an unrelated product feature that does not alter MCP/skill contracts.

• Required context: canonical repository and branch, running service/container and version,

current toolset descriptor, affected state owner, working analogue, and exact user-visible failure or desired contract.

Non-negotiable pattern

1. Resolve the target. Distinguish source checkout, generated bundle, installed package,

running service/container, state volume, reverse proxy and external client snapshot. Never edit a temporary audit clone or first search match.

1. Observe. Reproduce and preserve the first concrete error or behavioral evidence.
2. Map. Trace client/descriptor → route → schema → dispatcher → shared host guard/state →

response → UI/client. For skills, trace root → trust → id → search/read → model context.

1. Bound. List scope, trust, audit, limits, cursors, client cache, cross-repo names, process

lifetime, persistence, domain/port and release constraints. Separate fact/inference/unknown.

1. Reverse-engineer. Find the nearest working sibling and reuse its authoritative seam.
2. Experiment. Run the smallest test that can reject one hypothesis; do not stack guesses or

retry unchanged inputs.

1. Change. Make one reversible mutation in the authoritative layer and preserve state.
2. Prove. Verify targeted contract, build, runtime and external-client behavior before

finishing.

Tool contract

For a public MCP tool, inspect and update all affected surfaces:

• stable public name and input schema;
• scope tier plus list-time and call-time enforcement;
• thin delegation to lib/host or another existing guarded capability;
• audit action/target for mutation or exec;
• rate, size, timeout, path, pagination and continuation limits;
• Alfa/MCP parity or an explicit documented MCP-only reason;
• toolset version/hash/count and public descriptor;
• downstream cached action mappings and other external client snapshots;
• current docs, progress rationale and client-rescan instructions.

Never create a parallel raw fs/child_process path inside a tool. Never rename a public tool without treating its MSO name/schema as a public compatibility contract.

Skill contract

For a trusted workflow skill:

• generate with bun run skill:new and keep it under 200 lines;
• make use/do-not-use triggers and required context precise enough for semantic routing;
• prefer bounded direct tools; use one workflow_start for multi-step work and carry its exact

workflow_id on every operational call;

• define expected state, targeted checks, runtime/visual proof, diff boundary and rollback;
• keep volatile project facts and every secret out of the skill;
• validate with bun run skill:check and confirm skills_search routes intended prompts;
• remember that trust is derived from root/provenance/ownership, never frontmatter.

MCP App/UI contract

When a feature includes a ChatGPT/MCP App surface:

• keep ordinary data tools headless and bind only explicit render tools to ui.resourceUri;
• serve text/html;profile=mcp-app and prefer the host-neutral ui/* bridge:

ui/initialize → initialized → tool input/result notifications → tools/call or ui/message;

• keep window.openai APIs only as documented compatibility fallbacks, never the sole portable path;
• bump a versioned ui:// resource URI when host-visible behavior changes and keep old URIs read-only;
• prove the real postMessage lifecycle in browser E2E instead of only checking metadata or HTML strings;
• keep .app.json package bindings separate from UI resources and authorization. Persist only canonical

asdk_app_, connector_, or templated_apps_ IDs; never persist a plugin_... URL identifier.

For deterministic repeated validation/search steps, prefer a bounded script referenced by the skill, then verify the script result before returning. Do not turn script convenience into a new authority path.

Project function contract

Keep project function names as data behind the stable project_capabilities and project_function_call pair. Validate .mso/functions.json, declared arguments, working directory, scope and refusal behavior. Do not add one global MCP tool per project function.

Modular project MCPs

For one-connector workflows spanning a project MCP, read Project MCP connections. Use declared aliases and private named integrations; downstream tokens define identity, not owner IDs or assistant labels. Reuse generic discovery/call tools, preserve endpoint binding, allowlists, revocation and bounded pagination. A configured declaration or fixture pass is not proof of authenticated access to the user's live app.

Fast route

• One direct operation: use the exact bounded tool and verify it.
• Multi-step task: call workflow_start once with complete intent/project/constraints; do not

call skills_search first for the same task.

• Repository search, Git, tests, build, or three or more related reads: use one narrow

exec_run batch when exec scope is available.

• Long-running MSO release: use the repository handoff path and poll its owner unit/log; replacing

mso.service terminates the MCP request that initiated it.

Verification contract

• Expected state: source, descriptor, scope, audit, skill/tool routing and live behavior agree.
• Targeted checks: schema/helper tests; list/call scope tests; audit/limit tests; skill check;

parity and external mapping checks.

• Runtime proof: live GET /mcp toolset signature, service health/version, state ownership,

and a real call through the changed path.

• Visual proof: required for UI/mobile/auth changes; test actual scroll/viewport/session close

and reopen rather than inferring from CSS or cookie source.

• Diff boundary: MCP/skill/doc surfaces required by the contract only; no provider, runtime,

domain or unrelated refactor changes without separate justification.

Failure and rollback

• Preserve the first error before retrying.
• Stop on ambiguous project/runtime identity, missing scope, or truncated discovery without a

continuation cursor.

• Roll back the smallest changed layer while preserving state and configured domains.
• Never force-push, delete user data, expose credentials, or claim live success from source/build

evidence alone.

Recipe memory

Save only redacted, replayable steps and the pattern that worked. Do not store file bodies, tokens, cookies, private URLs, auth callbacks, secrets, or volatile PIDs. A failed attempt is evidence, not the replacement for a verified recipe.