phuryn/product-engineering / app-stack/skills/embedded-agents-messages-api
embedded-agents-messages-api
VerifiedBuilding, adding or wiring up an agent or an agent chat inside a Next.js app: embed Claude agents on the Messages API, the default way.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| examples/knowledge-agent.live.test.ts | script | 1.2 KB |
| examples/knowledge-agent/AGENTS.md | markdown | 2.0 KB |
| examples/knowledge-agent/knowledge/jtbd.md | markdown | 3.3 KB |
| examples/knowledge-agent/knowledge/llms.md | markdown | 6.1 KB |
| examples/knowledge-agent/knowledge/okrs.md | markdown | 2.7 KB |
| examples/knowledge-agent/knowledge/product-strategy.md | markdown | 3.8 KB |
| examples/knowledge-agent/knowledge/product-vision.md | markdown | 3.8 KB |
| examples/research-agent.live.test.ts | script | 1.1 KB |
| examples/research-agent/.mcp.json | config | 277 B |
| examples/research-agent/AGENTS.md | markdown | 2.5 KB |
| reference/playbook.md | markdown | 23.0 KB |
| scripts/discover-mcp-tools.mjs | script | 3.0 KB |
| scripts/new-agent.mjs | script | 1.9 KB |
| templates/agent-mcp.ts | script | 4.9 KB |
| templates/agent.test.ts | script | 18.0 KB |
| templates/agent.ts | script | 18.6 KB |
| templates/agents.live.test.ts | script | 1.9 KB |
| templates/route.ts | script | 2.4 KB |
scripts/discover-mcp-tools.mjs
View on GitHub#!/usr/bin/env node
// List the tools each MCP server in an embedded agent's .mcp.json offers, beside the ones its
// `allowedTools` grants today. Connects to each server the way the wrapper does (src/lib/agent-mcp.ts)
// and asks it for its tools — no model call, no cost. Run from the repo root, with the agent's
// secrets in the environment:
// node --env-file=.env <skill dir>/scripts/discover-mcp-tools.mjs <agent>
// It writes nothing: grant only the tools the agent's job needs, by editing `allowedTools`.
import { existsSync, readFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const agent = process.argv[2];
if (!agent || !/^[a-z0-9][a-z0-9-]*$/.test(agent)) {
console.error('Usage: discover-mcp-tools.mjs <agent>');
process.exit(2);
}
const file = join(resolve(process.cwd(), '.claude', 'agents', agent), '.mcp.json');
if (!existsSync(file)) {
console.log(`${agent} has no .mcp.json: nothing to discover.`);
process.exit(0);
}
const missing = new Set();
const expand = (v) =>
typeof v === 'string' ? v.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, n) => process.env[n] || (missing.add(n), ''))
: Array.isArray(v) ? v.map(expand)
: v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, expand(x)]))
: v;
let failed = false;
for (const [name, declared] of Object.entries(JSON.parse(readFileSync(file, 'utf8')).mcpServers ?? {})) {
const { allowedTools: granted = [], ...server } = declared;
missing.clear();
const s = expand(server);
console.log(`\n${name}`);
if (missing.size) { failed = true; console.log(` not started: ${[...missing].join(', ')} not set`); continue; }
const client = new Client({ name: `discover-${name}`, version: '1.0.0' });
try {
// The server's own error output is shown here (and only here): it is the clue when a server won't start.
await client.connect(s.type === 'http'
? new StreamableHTTPClientTransport(new URL(s.url), { requestInit: { headers: s.headers } })
: new StdioClientTransport({ command: s.command, args: s.args, env: s.env, stderr: 'inherit' }));
const found = [];
let cursor;
do {
const page = await client.listTools(cursor ? { cursor } : undefined);
found.push(...page.tools.map((t) => t.name));
cursor = page.nextCursor;
} while (cursor);
for (const t of found) console.log(` ${granted.includes(t) ? 'granted ' : 'available'} ${t}`);
for (const t of granted.filter((g) => !found.includes(g))) console.log(` STALE ${t} (granted, but the server no longer offers it)`);
} catch (err) {
failed = true;
console.log(` did not connect: ${err instanceof Error ? err.message : err}`);
} finally {
await client.close().catch(() => {});
}
}
process.exit(failed ? 1 : 0);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |