Skip to main content
skill CX Codex

generate-codeful-mcp-tool — Claude Code skill: MCP tool

The generate-codeful-mcp-tool skill builds a JavaScript server runtime and registration metadata for a codeful MCP tool. Use it for Dataverse-backed tools or an MCP App widget.

MIT ★ 1,167 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add microsoft/power-platform-skills
/plugin install mcp-apps@power-platform-skills
Open on GitHub

What generate-codeful-mcp-tool does

The skill produces two files for one MCP tool: <tool-name>.tool.js with the server implementation and <tool-name>.tool.json with registration metadata. The JavaScript module exports runTool({ toolInput, dataApi }); the JSON sidecar defines the name, description, input and output schemas, plus MCP annotations.

Before generation, the agent needs the tool purpose, a kebab-case name, input fields, expected output, and any Dataverse operations. For a Dataverse tool, it checks tables through PAC CLI and uses verified logical names and columns. Generation must stop when the Dataverse schema cannot be verified, so invented tables and fields are not used.

The skill runs in Claude Code with Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, and Skill. It can also pair the server logic with an MCP App widget when that is part of the request.

What it helps with

  • create a JavaScript runtime for an MCP tool
  • define MCP registration metadata in JSON
  • write a runTool function around dataApi
  • verify Dataverse tables and columns
  • pair MCP server logic with an MCP App widget

Example prompts for the agent

  • Create a codeful MCP tool named account-summary that reads Dataverse data and returns a summary.
  • Generate <tool-name>.tool.js and <tool-name>.tool.json for this input contract and expected result: ...
  • Check the Dataverse schema through PAC CLI and prepare the server logic for an MCP App widget.

How to install generate-codeful-mcp-tool

1Plugin marketplace

/plugin marketplace add microsoft/power-platform-skills
/plugin install mcp-apps@power-platform-skills

This installs the whole mcp-apps plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/power-platform-skills --skill generate-codeful-mcp-tool -a claude-code

3Manually: put the files in place

~/.claude/skills/generate-codeful-mcp-tool/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/generate-codeful-mcp-tool/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about generate-codeful-mcp-tool

How do I install generate-codeful-mcp-tool in Claude Code?

First add the marketplace with /plugin marketplace add microsoft/power-platform-skills, then install the plugin with /plugin install mcp-apps@power-platform-skills.

What does generate-codeful-mcp-tool do?

It creates a self-contained JavaScript runtime and JSON registration metadata for a codeful MCP tool. The output includes runTool, input and output schemas, and behavior annotations.

What is required for a Dataverse-backed tool?

Provide the tool purpose, input contract, expected result, and the Dataverse tables involved. The skill checks the environment through PAC CLI and takes column names from generated types.

Source text

SKILL.md · MIT
---
name: generate-codeful-mcp-tool
version: 1.0.0
description: >
  Generate a self-contained JavaScript server runtime and registration metadata
  for an MCP codeful tool.
  Use when the user asks to create a codeful MCP tool, generate server logic for
  an MCP tool, write a runTool function, build a Dataverse-backed MCP tool, or
  pair MCP server logic with an MCP App widget.
author: Microsoft Corporation
argument-hint: <tool purpose, inputs, and expected result>
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
---

**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:**
- Host API types: [codeful-tool-host-data-api.d.ts](../../references/codeful-tool-host-data-api.d.ts)
- Known-good tool: [account-summary.tool.js](../../samples/account-summary.tool.js)
- Known-good metadata: [account-summary.tool.json](../../samples/account-summary.tool.json)
- Widget generation: [generate-mcp-app-ui](../generate-mcp-app-ui/SKILL.md)

---

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:

```javascript
await runTool({ toolInput, dataApi });
```

## Required information

Before generating, establish:

1. 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.
2. 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.
3. The expected result, preferably as a representative output object.
4. Whether it reads or writes Dataverse, the requested tables in business terms, and
   whether any write creates, appends, updates, overwrites, or deletes state.
5. 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:

```text
${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:

1. Confirm PAC CLI is authenticated to the intended environment.
2. Discover candidate tables:

   ```powershell
   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.
3. Create a unique temporary directory outside the final output path and generate types:

   ```powershell
   pac model genpage generate-types --data-sources "logical1,logical2" --output-file "<temp>/RuntimeTypes.ts"
   ```

4. Read `RuntimeTypes.ts`. Extract the registered tables, exact readable/writable logical
   columns, lookup shapes, choice names, and raw numeric choice values.
5. 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:

  ```javascript
  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:

```json
{
  "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`](https://modelcontextprotocol.io/specification/2025-06-18/schema#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:

```javascript
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:

```javascript
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:

```javascript
return { structuredContent: businessPayload };
```

Do not mix envelope keys with unrelated top-level business fields.

## Phase 4: Validate

Before reporting completion:

1. Confirm exactly one final `.tool.js` and one matching `.tool.json` were created for
   this skill.
2. 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.
3. 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`.
4. Grep the output for imports, `require`, placeholders, guessed columns, and unsupported
   host access.
5. 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.
6. 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`.
7. Delete all temporary schema artifacts.

## Optional MCP App handoff

When the user asks for a widget:

1. Finish and validate the paired `.tool.js` and `.tool.json` first.
2. 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).
3. 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.
4. 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.

© Microsoft Corporation · MIT · microsoft/power-platform-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set157

The whole set →
author-webpage-content The author-webpage-content skill for Claude Code generates and updates localized HTML for PAC CLI-downloaded Power Pages sites, building Design Studio layouts without manual tag edits. CX Codex +1 ★ 1,167repo stars add-sample-data add-sample-data — a Claude Code skill that seeds Dataverse tables with sample records so you can quickly set up test data for Power Pages demos. CX Codex +1 ★ 1,167repo stars enable-tables-offline enable-tables-offline is a Power Platform skill that sets IsAvailableOffline and ChangeTrackingEnabled on Dataverse tables so they can be added to a Mobile Offline Profile. CX Codex +1 ★ 1,167repo stars generate-mcp-app-ui generate-mcp-app-ui builds single-file HTML widgets for MCP tools using test JSON output, supporting fully self-contained builds or public CDN scripts. CX Codex +1 ★ 1,167repo stars scan-site scan-site scans a live Power Pages site for security issues and turns the report into plain language. Handy before a production push, or when you need fresh findings. CX Codex +1 ★ 1,167repo stars generate-ppmplugin generate-ppmplugin orchestrates the end-to-end build and audit for third-party .ppmplugin files in Power Apps, coordinating Android and iOS compilation into a verified bundle. CX Codex +1 ★ 1,167repo stars add-sharepoint add-sharepoint is a Claude Code skill that connects SharePoint lists and libraries to a Power Apps mobile app, using existing lists or planning and creating new ones. CX Codex +1 ★ 1,167repo stars add-pdf-report add-pdf-report is a Claude Code skill that builds local PDF reports from app data using expo-print. It runs through /add-native and does not launch on its own. CX Codex +1 ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open