Skip to content

emit-ts.md

Latest commit

 

History

History
98 lines (75 loc) · 3.57 KB

emit-ts.md

File metadata and controls

98 lines (75 loc) · 3.57 KB
summary How to generate `.d.ts` files or typed client helpers with mcporter emit-ts.
read_when
Adding new emit-ts behavior or troubleshooting generated clients

mcporter emit-ts

mcporter emit-ts turns a configured MCP server into TypeScript artifacts so agents, tests, and tooling can consume the server through strongly typed APIs. It reuses the same buildToolDoc() data that powers mcporter list, so doc comments, parameter hints, and signatures stay perfectly in sync. For a broader overview of every CLI command, see docs/cli-reference.md.

mcporter emit-ts <server> --out linear-client.ts \
  [--mode types|client] \
  [--include-optional]
  • --mode types (default) emits a .d.ts interface (LinearTools) with docblocks + promisified signatures. Missing output schemas fall back to CallResult.
  • --mode client emits both the interface (auto-derived .d.ts) and an executable .ts helper that wraps createServerProxy. Each method returns a CallResult, and the factory exposes a close() helper for runtimes the client creates.
  • --include-optional mirrors mcporter list --all-parameters, ensuring every parameter is shown even when optional.

Outputs overwrite existing files automatically so you can regenerate artifacts whenever the server schema changes.

Examples

1. Types-only header

mcporter emit-ts linear --out types/linear-tools.d.ts

Produces:

import type { CallResult } from 'mcporter';

export interface LinearTools {
  /**
   * List comments for a specific Linear issue.
   *
   * @param issueId The issue ID
   */
  list_comments(params: { issueId: string }): Promise<CallResult>;
}

Include the file in your agent/project and you can type-check code like const result = await proxy.list_comments({ issueId: '...' });.

2. Client wrappers

mcporter emit-ts linear --mode client --out clients/linear.ts

Generates two files:

  • clients/linear.d.ts – same interface as the types-only mode.
  • clients/linear.ts – imports createRuntime, createServerProxy, and createCallResult, then exposes a createLinearClient() factory:
const client = await createLinearClient({ configPath: './mcporter.json' });
const comments = await client.list_comments({ issueId: 'LIN-1234' });
console.log(comments.text());
await client.close();

If you pass an existing runtime ({ runtime }), the factory reuses it; the returned object’s close() becomes a no-op.

Flags

| Flag | Description | | -------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------- | | --out <path> | Required. .d.ts target for types, .ts target for client. | | --mode types | client | Output kind (defaults to types). | | --types-out <path> | Optional override for the .d.ts file when --mode client. Default: derive from --out. | | --include-optional | Include every parameter (not just the minimum 5 + required). | | --json | Emit a JSON summary describing the emitted file(s) instead of plain-text logs. |

Testing

tests/emit-ts.test.ts covers:

  • Template rendering (doc comments, Promise<…> return types, proxy wrappers).
  • End-to-end CLI invocation with a stub runtime, ensuring both .ts and .d.ts files are written successfully.