Triggers: codeful MCP tool, MCP server tool, generate runTool, MCP tool JavaScript,
Dataverse MCP tool, server logic for MCP App
Keywords: mcp apps, codeful tool, runTool, dataApi, Dataverse, server runtime
Aliases: /generate-codeful-mcp-tool, /codeful-tool
References:
You generate a matched pair of files for one MCP tool:
<tool-name>.tool.js: the complete JavaScript server implementation.
<tool-name>.tool.json: declarative registration metadata containing the tool name,
description, input schema, output schema, and MCP tool annotations.
The host imports the JavaScript module and calls:
await runTool({ toolInput, dataApi });
Required information
Before generating, establish:
- The tool's purpose and kebab-case tool name. Use the purpose to write a concise,
model-actionable tool description; ask only when the intended behavior is ambiguous.
- Its input fields, types, required fields, and constraints. Accept a JSON Schema, a
representative input object, or an exact field description. Never guess the input shape.
- The expected result, preferably as a representative output object.
- Whether it reads or writes Dataverse, the requested tables in business terms, and
whether any write creates, appends, updates, overwrites, or deletes state.
- Whether the user also wants an MCP App widget.
Ask only for information that is missing. A sample input/output is preferred but not
mandatory when the user has supplied an equally precise contract.
Phase 1: Read the runtime and metadata contracts
Read:
${PLUGIN_ROOT}/references/codeful-tool-host-data-api.d.ts
${PLUGIN_ROOT}/samples/account-summary.tool.js
${PLUGIN_ROOT}/samples/account-summary.tool.json
The generated runtime is plain ESM JavaScript, and the sidecar is plain JSON. Type files
are generation-time references only and MUST NOT be imported by the output.
Phase 2: Verify Dataverse schema when needed
Skip this phase when the tool does not use Dataverse.
For a Dataverse-backed tool:
Confirm PAC CLI is authenticated to the intended environment.
Discover candidate tables:
pac model list-tables --search "table terms"
--search is substring-based. Post-filter its output and accept a table only when its
logical name exactly matches the selected result. If multiple tables remain plausible,
ask the user to choose.
Create a unique temporary directory outside the final output path and generate types:
pac model genpage generate-types --data-sources "logical1,logical2" --output-file "<temp>/RuntimeTypes.ts"
Read RuntimeTypes.ts. Extract the registered tables, exact readable/writable logical
columns, lookup shapes, choice names, and raw numeric choice values.
Use ONLY names and values verified in that file. Custom columns are unpredictable; do
not derive them from display names.
If discovery or type generation fails, stop and report the error. Do not fall back to
invented tables or columns. Delete the temporary types and directory after validation so
the final output contains only the requested .tool.js, .tool.json, and optional
widget files.
Phase 3: Generate the paired tool artifacts
Write <tool-name>.tool.js and <tool-name>.tool.json in the user's working directory
unless they requested another output directory. Both files MUST use the same basename,
which MUST equal the confirmed kebab-case tool name.
The JavaScript file MUST:
Export exactly one MCP entry point named runTool, preferably:
export async function runTool({ toolInput, dataApi }) {
// complete implementation
}
Be self-contained JavaScript with no runtime imports, packages, network calls,
filesystem access, environment-variable access, or generated-type dependency.
Validate all externally supplied toolInput before using it. Apply bounds to counts and
escape values interpolated into OData filters.
Use singular Dataverse entity logical names. Use exact logical column names in select,
filter, orderBy, and row objects.
Read choice and lookup labels from
"<column>@OData.Community.Display.V1.FormattedValue".
Access query rows through page.rows. Follow page.loadMoreRows() only while
page.hasMoreRows is true and the function exists.
Set lookups through the verified _<field>_value shape from RuntimeTypes.ts; never
emit raw Web API @odata.bind keys.
Let dataApi failures throw. Catch only when adding useful context, and rethrow with the
original error as the cause. Never return a success-shaped fallback after a failed read
or write.
Contain no placeholders, TODOs, ellipses, test credentials, or real environment IDs.
Return JSON-serializable values only. Never return loadMoreRows, functions, class
instances, or cyclic objects.
Emit telemetry only when the user explicitly asks for it, and never include tool inputs,
row contents, identifiers, or other user data in telemetry properties.
The JSON sidecar MUST be valid JSON with exactly these top-level fields:
{
"name": "account-summary",
"description": "Search accounts and return revenue and status summaries.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"properties": {}
}
}
name: exactly the confirmed tool name and the shared file basename.
description: concise, model-actionable guidance explaining what the tool does and when
to call it. Do not copy the user's prompt verbatim or include implementation details.
annotations: MCP
ToolAnnotations
describing the tool's behavior. Always emit all four boolean hints:
readOnlyHint: true only when the tool cannot modify Dataverse or any other state.
destructiveHint: true when the tool may delete, overwrite, or otherwise cause a
destructive update. Set it to false for read-only tools and non-destructive creates
or additive writes.
idempotentHint: true when repeated calls with the same valid input have no
additional effect. Reads, deterministic calculations, and updates that set the same
values are idempotent; creates and append-style operations are not.
openWorldHint: always false because the codeful runtime cannot access arbitrary
external systems.
Infer these values from the generated implementation and requested behavior. If the
write semantics are genuinely ambiguous, ask before generating rather than guessing.
Treat annotations as advisory metadata, not as a substitute for runtime validation or
authorization.
inputSchema: the complete JSON Schema for toolInput. Use an object root, list every
accepted field under properties, identify required fields with required, encode
runtime constraints such as bounds, formats, enums, and array item shapes, and set
additionalProperties: false unless the user explicitly requires extensible input.
outputSchema: the JSON Schema for the model-visible structuredContent business
payload. For a plain-object return, describe the complete returned object because the
host promotes it to structuredContent. For an envelope return, describe only its
structuredContent property. Never include content, authored meta, or runtime
_meta in outputSchema.
Use standard JSON Schema keywords only. Do not include credentials, environment
identifiers, Dataverse discovery artifacts, host configuration, JavaScript expressions,
comments, or placeholders in the sidecar.
Result-channel contract
Choose the smallest correct result shape.
Simple structured result
Return a plain object when all useful output belongs in model-visible structured data:
return { records, totalCount: records.length };
The host promotes that object to MCP structuredContent.
Partitioned MCP result
Return an envelope when the channels have different audiences:
return {
content: `Found ${records.length} records.`,
structuredContent: { records },
meta: { preferredView: "table" },
};
content: model-visible conversational text, either a string or text content blocks.
structuredContent: model-visible machine-readable object.
meta: widget-only object. The host maps it to MCP _meta; widgets read result._meta.
The names content, structuredContent, and meta are reserved envelope keys. If a
business payload naturally has any of those keys, wrap the whole payload explicitly:
return { structuredContent: businessPayload };
Do not mix envelope keys with unrelated top-level business fields.
Phase 4: Validate
Before reporting completion:
- Confirm exactly one final
.tool.js and one matching .tool.json were created for
this skill.
- Import the file as an ESM data URL with Node.js and assert that
runTool is a function.
Importing MUST NOT execute data access or other top-level side effects.
- Parse the sidecar with
JSON.parse. Confirm it has exactly name, description,
annotations, inputSchema, and outputSchema; the name matches both filenames;
all four annotation hints are booleans, openWorldHint is false, the other hints
match the implementation's actual behavior, both schemas have object roots, and every
input constraint enforced by the runtime is represented in inputSchema.
- Grep the output for imports,
require, placeholders, guessed columns, and unsupported
host access.
- When representative input/output was supplied, invoke
runTool with an in-memory mock
dataApi from an inline Node script. Do not create a persistent test file.
- Confirm the returned value matches the requested result contract, contains no
functions or non-serializable values, and its structured payload conforms to
outputSchema. Confirm the representative input conforms to inputSchema.
- Delete all temporary schema artifacts.
Optional MCP App handoff
When the user asks for a widget:
- Finish and validate the paired
.tool.js and .tool.json first.
- Build a representative result sample:
- Plain tool return -> treat it as
structuredContent.
- Envelope return -> pass
content, structuredContent, and _meta (renamed from the
authored meta field).
- Invoke
generate-mcp-app-ui with the visual requirements, tool name, input sample, and
representative full result. Forward an explicit CDN policy from the user's request.
If none was supplied, let the UI skill ask its required CDN-policy question; do not
assume public URLs are allowed.
- Keep the outputs separate: one
.tool.js, one .tool.json, and one single-file
.html using the selected CDN policy.
Refinement
When editing an existing codeful tool, read both paired files and change only the
requested behavior. Keep runtime validation and metadata schemas synchronized. Re-run
schema verification if the edit introduces a table, column, lookup, or choice value not
already verified for the file.
Completion response
State both generated tool file paths and summarize the description, tool annotations,
input contract, and structured result contract. If a widget was requested, also state the
HTML path and which result channels it consumes.
1---2name: generate-codeful-mcp-tool3version: 1.0.04description: >5 Generate a self-contained JavaScript server runtime and registration metadata6 for an MCP codeful tool.7 Use when the user asks to create a codeful MCP tool, generate server logic for8 an MCP tool, write a runTool function, build a Dataverse-backed MCP tool, or9 pair MCP server logic with an MCP App widget.10author: Microsoft Corporation11argument-hint: <tool purpose, inputs, and expected result>12user-invocable: true13allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill14metadata:15 source: https://skillmd.com/skills/microsoft/generate-codeful-mcp-tool16---1718**Triggers:** codeful MCP tool, MCP server tool, generate runTool, MCP tool JavaScript,19Dataverse MCP tool, server logic for MCP App2021**Keywords:** mcp apps, codeful tool, runTool, dataApi, Dataverse, server runtime2223**Aliases:** /generate-codeful-mcp-tool, /codeful-tool2425**References:**26- Host API types: [codeful-tool-host-data-api.d.ts](../../references/codeful-tool-host-data-api.d.ts)27- Known-good tool: [account-summary.tool.js](../../samples/account-summary.tool.js)28- Known-good metadata: [account-summary.tool.json](../../samples/account-summary.tool.json)29- Widget generation: [generate-mcp-app-ui](../generate-mcp-app-ui/SKILL.md)3031---3233You generate a matched pair of files for one MCP tool:3435- `<tool-name>.tool.js`: the complete JavaScript server implementation.36- `<tool-name>.tool.json`: declarative registration metadata containing the tool name,37 description, input schema, output schema, and MCP tool annotations.3839The host imports the JavaScript module and calls:4041```javascript42await runTool({ toolInput, dataApi });43```4445## Required information4647Before generating, establish:48491. The tool's purpose and kebab-case tool name. Use the purpose to write a concise,50 model-actionable tool description; ask only when the intended behavior is ambiguous.512. Its input fields, types, required fields, and constraints. Accept a JSON Schema, a52 representative input object, or an exact field description. Never guess the input shape.533. The expected result, preferably as a representative output object.544. Whether it reads or writes Dataverse, the requested tables in business terms, and55 whether any write creates, appends, updates, overwrites, or deletes state.565. Whether the user also wants an MCP App widget.5758Ask only for information that is missing. A sample input/output is preferred but not59mandatory when the user has supplied an equally precise contract.6061## Phase 1: Read the runtime and metadata contracts6263Read:6465```text66${PLUGIN_ROOT}/references/codeful-tool-host-data-api.d.ts67${PLUGIN_ROOT}/samples/account-summary.tool.js68${PLUGIN_ROOT}/samples/account-summary.tool.json69```7071The generated runtime is plain ESM JavaScript, and the sidecar is plain JSON. Type files72are generation-time references only and MUST NOT be imported by the output.7374## Phase 2: Verify Dataverse schema when needed7576Skip this phase when the tool does not use Dataverse.7778For a Dataverse-backed tool:79801. Confirm PAC CLI is authenticated to the intended environment.812. Discover candidate tables:8283 ```powershell84 pac model list-tables --search "table terms"85 ```8687 `--search` is substring-based. Post-filter its output and accept a table only when its88 logical name exactly matches the selected result. If multiple tables remain plausible,89 ask the user to choose.903. Create a unique temporary directory outside the final output path and generate types:9192 ```powershell93 pac model genpage generate-types --data-sources "logical1,logical2" --output-file "<temp>/RuntimeTypes.ts"94 ```95964. Read `RuntimeTypes.ts`. Extract the registered tables, exact readable/writable logical97 columns, lookup shapes, choice names, and raw numeric choice values.985. Use ONLY names and values verified in that file. Custom columns are unpredictable; do99 not derive them from display names.100101If discovery or type generation fails, stop and report the error. Do not fall back to102invented tables or columns. Delete the temporary types and directory after validation so103the final output contains only the requested `.tool.js`, `.tool.json`, and optional104widget files.105106## Phase 3: Generate the paired tool artifacts107108Write `<tool-name>.tool.js` and `<tool-name>.tool.json` in the user's working directory109unless they requested another output directory. Both files MUST use the same basename,110which MUST equal the confirmed kebab-case tool name.111112The JavaScript file MUST:113114- Export exactly one MCP entry point named `runTool`, preferably:115116 ```javascript117 export async function runTool({ toolInput, dataApi }) {118 // complete implementation119 }120 ```121122- Be self-contained JavaScript with no runtime imports, packages, network calls,123 filesystem access, environment-variable access, or generated-type dependency.124- Validate all externally supplied `toolInput` before using it. Apply bounds to counts and125 escape values interpolated into OData filters.126- Use singular Dataverse entity logical names. Use exact logical column names in `select`,127 `filter`, `orderBy`, and row objects.128- Read choice and lookup labels from129 `"<column>@OData.Community.Display.V1.FormattedValue"`.130- Access query rows through `page.rows`. Follow `page.loadMoreRows()` only while131 `page.hasMoreRows` is true and the function exists.132- Set lookups through the verified `_<field>_value` shape from `RuntimeTypes.ts`; never133 emit raw Web API `@odata.bind` keys.134- Let `dataApi` failures throw. Catch only when adding useful context, and rethrow with the135 original error as the cause. Never return a success-shaped fallback after a failed read136 or write.137- Contain no placeholders, TODOs, ellipses, test credentials, or real environment IDs.138- Return JSON-serializable values only. Never return `loadMoreRows`, functions, class139 instances, or cyclic objects.140- Emit telemetry only when the user explicitly asks for it, and never include tool inputs,141 row contents, identifiers, or other user data in telemetry properties.142143The JSON sidecar MUST be valid JSON with exactly these top-level fields:144145```json146{147 "name": "account-summary",148 "description": "Search accounts and return revenue and status summaries.",149 "annotations": {150 "readOnlyHint": true,151 "destructiveHint": false,152 "idempotentHint": true,153 "openWorldHint": false154 },155 "inputSchema": {156 "type": "object",157 "properties": {}158 },159 "outputSchema": {160 "type": "object",161 "properties": {}162 }163}164```165166- `name`: exactly the confirmed tool name and the shared file basename.167- `description`: concise, model-actionable guidance explaining what the tool does and when168 to call it. Do not copy the user's prompt verbatim or include implementation details.169- `annotations`: MCP170 [`ToolAnnotations`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations)171 describing the tool's behavior. Always emit all four boolean hints:172 - `readOnlyHint`: `true` only when the tool cannot modify Dataverse or any other state.173 - `destructiveHint`: `true` when the tool may delete, overwrite, or otherwise cause a174 destructive update. Set it to `false` for read-only tools and non-destructive creates175 or additive writes.176 - `idempotentHint`: `true` when repeated calls with the same valid input have no177 additional effect. Reads, deterministic calculations, and updates that set the same178 values are idempotent; creates and append-style operations are not.179 - `openWorldHint`: always `false` because the codeful runtime cannot access arbitrary180 external systems.181 Infer these values from the generated implementation and requested behavior. If the182 write semantics are genuinely ambiguous, ask before generating rather than guessing.183 Treat annotations as advisory metadata, not as a substitute for runtime validation or184 authorization.185- `inputSchema`: the complete JSON Schema for `toolInput`. Use an object root, list every186 accepted field under `properties`, identify required fields with `required`, encode187 runtime constraints such as bounds, formats, enums, and array item shapes, and set188 `additionalProperties: false` unless the user explicitly requires extensible input.189- `outputSchema`: the JSON Schema for the model-visible `structuredContent` business190 payload. For a plain-object return, describe the complete returned object because the191 host promotes it to `structuredContent`. For an envelope return, describe only its192 `structuredContent` property. Never include `content`, authored `meta`, or runtime193 `_meta` in `outputSchema`.194195Use standard JSON Schema keywords only. Do not include credentials, environment196identifiers, Dataverse discovery artifacts, host configuration, JavaScript expressions,197comments, or placeholders in the sidecar.198199## Result-channel contract200201Choose the smallest correct result shape.202203### Simple structured result204205Return a plain object when all useful output belongs in model-visible structured data:206207```javascript208return { records, totalCount: records.length };209```210211The host promotes that object to MCP `structuredContent`.212213### Partitioned MCP result214215Return an envelope when the channels have different audiences:216217```javascript218return {219 content: `Found ${records.length} records.`,220 structuredContent: { records },221 meta: { preferredView: "table" },222};223```224225- `content`: model-visible conversational text, either a string or text content blocks.226- `structuredContent`: model-visible machine-readable object.227- `meta`: widget-only object. The host maps it to MCP `_meta`; widgets read `result._meta`.228229The names `content`, `structuredContent`, and `meta` are reserved envelope keys. If a230business payload naturally has any of those keys, wrap the whole payload explicitly:231232```javascript233return { structuredContent: businessPayload };234```235236Do not mix envelope keys with unrelated top-level business fields.237238## Phase 4: Validate239240Before reporting completion:2412421. Confirm exactly one final `.tool.js` and one matching `.tool.json` were created for243 this skill.2442. Import the file as an ESM data URL with Node.js and assert that `runTool` is a function.245 Importing MUST NOT execute data access or other top-level side effects.2463. Parse the sidecar with `JSON.parse`. Confirm it has exactly `name`, `description`,247 `annotations`, `inputSchema`, and `outputSchema`; the name matches both filenames;248 all four annotation hints are booleans, `openWorldHint` is `false`, the other hints249 match the implementation's actual behavior, both schemas have object roots, and every250 input constraint enforced by the runtime is represented in `inputSchema`.2514. Grep the output for imports, `require`, placeholders, guessed columns, and unsupported252 host access.2535. When representative input/output was supplied, invoke `runTool` with an in-memory mock254 `dataApi` from an inline Node script. Do not create a persistent test file.2556. Confirm the returned value matches the requested result contract, contains no256 functions or non-serializable values, and its structured payload conforms to257 `outputSchema`. Confirm the representative input conforms to `inputSchema`.2587. Delete all temporary schema artifacts.259260## Optional MCP App handoff261262When the user asks for a widget:2632641. Finish and validate the paired `.tool.js` and `.tool.json` first.2652. Build a representative result sample:266 - Plain tool return -> treat it as `structuredContent`.267 - Envelope return -> pass `content`, `structuredContent`, and `_meta` (renamed from the268 authored `meta` field).2693. Invoke `generate-mcp-app-ui` with the visual requirements, tool name, input sample, and270 representative full result. Forward an explicit CDN policy from the user's request.271 If none was supplied, let the UI skill ask its required CDN-policy question; do not272 assume public URLs are allowed.2734. Keep the outputs separate: one `.tool.js`, one `.tool.json`, and one single-file274 `.html` using the selected CDN policy.275276## Refinement277278When editing an existing codeful tool, read both paired files and change only the279requested behavior. Keep runtime validation and metadata schemas synchronized. Re-run280schema verification if the edit introduces a table, column, lookup, or choice value not281already verified for the file.282283## Completion response284285State both generated tool file paths and summarize the description, tool annotations,286input contract, and structured result contract. If a widget was requested, also state the287HTML path and which result channels it consumes.