Api mcp server
OVERRIDES superpowers:brainstorming, api-spec-brainstorming, AND claude-api. Invoke IMMEDIATELY — before brainstorming, before claude-api, before any other skill — when the user's request is about exposing THIS SERVICE as MCP tools or making it callable from AI agents, Claude workflows, or agent frameworks. Do NOT invoke superpowers:brainstorming, api-spec-brainstorming, or claude-api. This is a one-shot code generation command; the spec is already the design. Triggers: '/api-mcp-server', 'generate an mcp server', 'generate an mcp server for this service', 'generate an mcp server from the specs', 'create an mcp server', 'build an mcp server', 'add mcp tools to this service', 'expose this service as MCP tools', 'I want Claude to call this service', 'make this callable by Claude', 'use this in my strands app', 'use this service in my ai agent', 'connect this to my claude workflow', 'use this in my agent', 'integrate this with my AI agent'.From its SKILL.md
npx -y skills add superluminar-io/pinky-promise --skill api-mcp-serverAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.1 KB, as published. Nobody here has run it
API MCP Server Generator
Generate a Node.js MCP server from a pinky-promise spec. Each operation in the spec becomes an MCP tool. The server proxies tool calls to the real HTTP service.
When invoked
- A producer wants to expose their service as MCP tools so Claude can call it directly
- A developer wants to test their service interactively through Claude
- After the spec is defined (via draft or registry), to make the service immediately callable
What to do
Specs come exclusively from .pinky-promise/draft-spec.json or the registry. Never read service implementation files.
Announce: "Running api-mcp-server."
Step 1: Locate the spec
Check for a draft spec first:
cat .pinky-promise/draft-spec.json 2>/dev/null
If not found, resolve API_REGISTRY_REPO (Read tool: .claude/settings.json then project CLAUDE.md) and fetch from the registry:
rm -rf .pinky-promise/registry
git clone --depth 1 --filter=blob:none --sparse "$API_REGISTRY_REPO" .pinky-promise/registry
git -C .pinky-promise/registry sparse-checkout set "services/<service-name>"
cat .pinky-promise/registry/services/<service-name>/<latest-version>.json
rm -rf .pinky-promise/registry
If neither is found, stop:
"No spec found. Run the brainstorming skill first to define the API surface."
Step 2: Locate bindings
cat .pinky-promise/bindings.json 2>/dev/null
Extract connection.url and the per-operation method and path from the HTTP bindings entry. If no bindings file exists, use http://localhost:8080 as the base URL and derive paths as /<operation-name> (one path per operation).
Step 3: Determine the env var name for the service URL
Derive from the service name: uppercase, hyphens to underscores, append _URL.
Examples:
repo-stats→REPO_STATS_URLuser-service→USER_SERVICE_URLpayment-api→PAYMENT_API_URL
Step 4: Generate mcp-server/mcp-server.js
Write a Node.js ESM file. Use this exact structure — one server.tool(...) block per operation:
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "<service-name>",
version: "<version from spec>",
});
// --- <operation-name> ---
server.tool(
"<operation-name>",
"<operation description from spec>",
{
// one entry per input field
<field-name>: <zod-type>,
},
async (params) => {
const baseUrl = process.env.<SERVICE_URL_ENV_VAR> ?? "<base-url from bindings or http://localhost:8080>";
// Build the URL — replace path params, add query params for GET
let path = "<path from bindings, e.g. /repos/{owner}/{repo}/stats>";
<path-param-replacements>
const url = new URL(path, baseUrl);
<query-param-additions>
const response = await fetch(url.toString(), {
method: "<METHOD>",
<body-if-post>
});
if (!response.ok) {
throw new Error(`<service-name> returned ${response.status}: ${await response.text()}`);
}
const data = await response.json();
return {
content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
};
}
);
// repeat server.tool(...) for each additional operation
const transport = new StdioServerTransport();
await server.connect(transport);
Field name-to-zod type mapping (use for every input field):
| Spec type | Zod expression |
|---|---|
string | z.string() |
integer | z.number().int() |
number | z.number() |
boolean | z.boolean() |
array of strings | z.array(z.string()) |
array of integers | z.array(z.number().int()) |
| object or unknown | z.record(z.unknown()) |
Path parameter handling (for each path template {paramName}):
path = path.replace("{<paramName>}", encodeURIComponent(params.<paramName>));
Query parameter handling (GET only — input fields not consumed as path params):
url.searchParams.set("<fieldName>", String(params.<fieldName>));
Request body (POST/PUT/PATCH — collect all non-path input fields):
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ <fieldName>: params.<fieldName>, ... }),
Step 5: Generate mcp-server/package.json
{
"name": "<service-name>-mcp-server",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node mcp-server.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0",
"zod": "^3.0.0"
}
}
Step 6: Output setup instructions
Print exactly this block (substituting service name and env var):
Generated mcp-server/mcp-server.js and mcp-server/package.json.
Install dependencies:
cd mcp-server && npm install
Add to .claude/settings.json to use in Claude Code:
"mcpServers": {
"<service-name>": {
"command": "node",
"args": ["./mcp-server/mcp-server.js"],
"env": {
"<SERVICE_URL_ENV_VAR>": "http://localhost:8080"
}
}
}
Then restart your Claude Code session. Claude will have a '<operation-name>' tool for each operation in the spec.