@zyphr-dev/mcp-server 0.1.0

package/src/integration/quickstart-types.ts

@@ -0,0 +1,31 @@
+// TODO(v0.3): auto-generate quickstart snippets from packages/sdk/<lang>/examples/
+// so docs and MCP output never drift. For v0.2 they are hand-maintained and
+// must mirror apps/docs/docs/channels/<channel>.md and apps/docs/docs/features/webhooks-security.md.
+import type { SdkLanguage } from '../schemas.js';
+
+export type QuickstartVariant = 'sdk' | 'webhook-handler';
+
+export interface QuickstartFile {
+  path: string;
+  purpose: string;
+  contents: string;
+  overwrite: boolean;
+}
+
+export interface QuickstartResult {
+  channel: string;
+  language: SdkLanguage;
+  framework: string | null;
+  variant: QuickstartVariant;
+  files: QuickstartFile[];
+  envVarsNeeded: string[];
+  nextSteps: string[];
+  docsUrl: string;
+}
+
+export interface QuickstartEntry {
+  sdk: QuickstartResult;
+  frameworks?: Record<string, QuickstartResult>;
+}
+
+export type QuickstartChannelMap = Partial<Record<SdkLanguage, QuickstartEntry>>;

package/src/integration/sdk-snippets.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { sdkLanguages, type SdkLanguage } from '../schemas.js';
+import { SDK_INSTALL_TABLE, resolveInstallEntry } from './sdk-snippets.js';
+
+const ENV_VAR_PATTERN: Record<SdkLanguage, RegExp> = {
+  node: /process\.env/,
+  python: /os\.environ/,
+  ruby: /ENV/,
+  go: /os\.Getenv/,
+  php: /getenv/,
+  csharp: /GetEnvironmentVariable/,
+};
+
+describe('SDK_INSTALL_TABLE', () => {
+  it.each(sdkLanguages.map((l) => [l]))('returns a complete entry for %s', (language) => {
+    const entry = SDK_INSTALL_TABLE[language];
+    expect(entry).toBeDefined();
+    expect(entry.installCommands.length).toBeGreaterThanOrEqual(1);
+    for (const c of entry.installCommands) {
+      expect(c.manager).toMatch(/\S/);
+      expect(c.command).toMatch(/\S/);
+    }
+    expect(entry.envVarsNeeded).toContain('ZYPHR_API_KEY');
+    expect(entry.initSnippet.init).toMatch(ENV_VAR_PATTERN[language]);
+    expect(entry.docsUrl).toMatch(/^https:\/\/docs\.zyphr\.dev\/sdks\//);
+  });
+
+  it('flags non-SDK languages as rest-client', () => {
+    expect(SDK_INSTALL_TABLE.python.kind).toBe('rest-client');
+    expect(SDK_INSTALL_TABLE.go.kind).toBe('rest-client');
+    expect(SDK_INSTALL_TABLE.php.kind).toBe('rest-client');
+  });
+
+  it('flags official SDK languages as sdk', () => {
+    expect(SDK_INSTALL_TABLE.node.kind).toBe('sdk');
+    expect(SDK_INSTALL_TABLE.ruby.kind).toBe('sdk');
+    expect(SDK_INSTALL_TABLE.csharp.kind).toBe('sdk');
+  });
+});
+
+describe('resolveInstallEntry', () => {
+  it('returns the full command list when no package manager override is given', () => {
+    const entry = resolveInstallEntry('node');
+    expect(entry.installCommands).toHaveLength(3);
+    expect(entry.installCommands.map((c) => c.manager).sort()).toEqual(['npm', 'pnpm', 'yarn']);
+  });
+
+  it('narrows to a single command when the package manager is recognized (case-insensitive)', () => {
+    const entry = resolveInstallEntry('node', 'YARN');
+    expect(entry.installCommands).toHaveLength(1);
+    expect(entry.installCommands[0]?.command).toBe('yarn add @zyphr-dev/node-sdk');
+  });
+
+  it('falls back to the full list when the package manager is not recognized', () => {
+    const entry = resolveInstallEntry('node', 'rye');
+    expect(entry.installCommands).toHaveLength(3);
+  });
+
+  it('does not mutate the source table when narrowing', () => {
+    resolveInstallEntry('python', 'poetry');
+    expect(SDK_INSTALL_TABLE.python.installCommands.length).toBeGreaterThan(1);
+  });
+});

package/src/integration/sdk-snippets.ts

@@ -0,0 +1,248 @@
+// TODO(v0.3): auto-generate these snippets from packages/sdk/<lang>/examples/
+// so docs and MCP output never drift. For v0.2 they are hand-maintained and
+// must mirror apps/docs/docs/sdks/<lang>.md exactly.
+import type { SdkLanguage } from '../schemas.js';
+
+export interface InstallCommand {
+  manager: string;
+  command: string;
+}
+
+export interface InitSnippet {
+  imports: string;
+  init: string;
+  fileExample: string;
+}
+
+export type SdkKind = 'sdk' | 'rest-client';
+
+export interface SdkInstallEntry {
+  language: SdkLanguage;
+  kind: SdkKind;
+  packageName: string;
+  registry: string;
+  registryUrl: string;
+  installCommands: InstallCommand[];
+  initSnippet: InitSnippet;
+  envVarsNeeded: string[];
+  docsUrl: string;
+  notes?: string;
+}
+
+const DOCS = 'https://docs.zyphr.dev/sdks';
+
+export const SDK_INSTALL_TABLE: Record<SdkLanguage, SdkInstallEntry> = {
+  node: {
+    language: 'node',
+    kind: 'sdk',
+    packageName: '@zyphr-dev/node-sdk',
+    registry: 'npm',
+    registryUrl: 'https://www.npmjs.com/package/@zyphr-dev/node-sdk',
+    installCommands: [
+      { manager: 'npm', command: 'npm install @zyphr-dev/node-sdk' },
+      { manager: 'yarn', command: 'yarn add @zyphr-dev/node-sdk' },
+      { manager: 'pnpm', command: 'pnpm add @zyphr-dev/node-sdk' },
+    ],
+    initSnippet: {
+      imports: "import { Zyphr } from '@zyphr-dev/node-sdk';",
+      init: "export const zyphr = new Zyphr({ apiKey: process.env.ZYPHR_API_KEY! });",
+      fileExample: 'src/lib/zyphr.ts',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/node`,
+  },
+  csharp: {
+    language: 'csharp',
+    kind: 'sdk',
+    packageName: 'ZyphrDev.SDK',
+    registry: 'NuGet',
+    registryUrl: 'https://www.nuget.org/packages/ZyphrDev.SDK',
+    installCommands: [
+      { manager: 'dotnet', command: 'dotnet add package ZyphrDev.SDK' },
+      { manager: 'nuget', command: 'Install-Package ZyphrDev.SDK' },
+    ],
+    initSnippet: {
+      imports: [
+        'using ZyphrDev.SDK.Api;',
+        'using ZyphrDev.SDK.Client;',
+        'using ZyphrDev.SDK.Model;',
+      ].join('\n'),
+      init: [
+        'var config = new Configuration',
+        '{',
+        '    ApiKey = new Dictionary<string, string>',
+        '    {',
+        '        { "X-API-Key", Environment.GetEnvironmentVariable("ZYPHR_API_KEY")! }',
+        '    }',
+        '};',
+        'var emails = new EmailsApi(config);',
+      ].join('\n'),
+      fileExample: 'Services/ZyphrClient.cs',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/csharp`,
+  },
+  ruby: {
+    language: 'ruby',
+    kind: 'sdk',
+    packageName: 'zyphr',
+    registry: 'RubyGems',
+    registryUrl: 'https://rubygems.org/gems/zyphr',
+    installCommands: [
+      { manager: 'gem', command: 'gem install zyphr' },
+      { manager: 'bundler', command: "bundle add zyphr" },
+    ],
+    initSnippet: {
+      imports: "require 'zyphr'",
+      init: [
+        'Zyphr.configure do |config|',
+        "  config.api_key['X-API-Key'] = ENV.fetch('ZYPHR_API_KEY')",
+        'end',
+      ].join('\n'),
+      fileExample: 'config/initializers/zyphr.rb',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/ruby`,
+  },
+  python: {
+    language: 'python',
+    kind: 'rest-client',
+    packageName: 'requests',
+    registry: 'PyPI',
+    registryUrl: 'https://pypi.org/project/requests/',
+    installCommands: [
+      { manager: 'pip', command: 'pip install requests' },
+      { manager: 'poetry', command: 'poetry add requests' },
+      { manager: 'uv', command: 'uv add requests' },
+    ],
+    initSnippet: {
+      imports: 'import os\nimport requests',
+      init: [
+        'ZYPHR_API_KEY = os.environ["ZYPHR_API_KEY"]',
+        'BASE_URL = "https://api.zyphr.dev/v1"',
+        '',
+        'headers = {',
+        '    "X-API-Key": ZYPHR_API_KEY,',
+        '    "Content-Type": "application/json",',
+        '}',
+        '',
+        'def zyphr_request(method, path, json=None, params=None):',
+        '    response = requests.request(',
+        '        method, f"{BASE_URL}{path}", headers=headers, json=json, params=params,',
+        '    )',
+        '    response.raise_for_status()',
+        '    return response.json()',
+      ].join('\n'),
+      fileExample: 'app/zyphr_client.py',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/python`,
+    notes:
+      'There is no official Zyphr Python SDK yet — the canonical integration is a thin REST wrapper around the requests library.',
+  },
+  go: {
+    language: 'go',
+    kind: 'rest-client',
+    packageName: 'net/http (stdlib)',
+    registry: 'stdlib',
+    registryUrl: 'https://pkg.go.dev/net/http',
+    installCommands: [
+      { manager: 'go', command: '# No install needed — net/http ships with Go.' },
+    ],
+    initSnippet: {
+      imports: [
+        'package zyphr',
+        '',
+        'import (',
+        '\t"bytes"',
+        '\t"encoding/json"',
+        '\t"fmt"',
+        '\t"io"',
+        '\t"net/http"',
+        '\t"os"',
+        ')',
+      ].join('\n'),
+      init: [
+        'const baseURL = "https://api.zyphr.dev/v1"',
+        '',
+        'type Client struct {',
+        '\tAPIKey     string',
+        '\tHTTPClient *http.Client',
+        '}',
+        '',
+        'func NewClient() *Client {',
+        '\treturn &Client{APIKey: os.Getenv("ZYPHR_API_KEY"), HTTPClient: &http.Client{}}',
+        '}',
+        '',
+        'func (c *Client) Do(method, path string, body any) ([]byte, error) {',
+        '\tvar buf io.Reader',
+        '\tif body != nil {',
+        '\t\tb, err := json.Marshal(body)',
+        '\t\tif err != nil { return nil, fmt.Errorf("marshal: %w", err) }',
+        '\t\tbuf = bytes.NewReader(b)',
+        '\t}',
+        '\treq, err := http.NewRequest(method, baseURL+path, buf)',
+        '\tif err != nil { return nil, err }',
+        '\treq.Header.Set("X-API-Key", c.APIKey)',
+        '\treq.Header.Set("Content-Type", "application/json")',
+        '\tresp, err := c.HTTPClient.Do(req)',
+        '\tif err != nil { return nil, err }',
+        '\tdefer resp.Body.Close()',
+        '\tdata, _ := io.ReadAll(resp.Body)',
+        '\tif resp.StatusCode >= 400 { return nil, fmt.Errorf("zyphr %d: %s", resp.StatusCode, data) }',
+        '\treturn data, nil',
+        '}',
+      ].join('\n'),
+      fileExample: 'internal/zyphr/client.go',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/go`,
+    notes:
+      'There is no official Zyphr Go SDK yet — the canonical integration is a thin REST wrapper around net/http.',
+  },
+  php: {
+    language: 'php',
+    kind: 'rest-client',
+    packageName: 'guzzlehttp/guzzle',
+    registry: 'Packagist',
+    registryUrl: 'https://packagist.org/packages/guzzlehttp/guzzle',
+    installCommands: [
+      { manager: 'composer', command: 'composer require guzzlehttp/guzzle' },
+    ],
+    initSnippet: {
+      imports: [
+        '<?php',
+        '',
+        'use GuzzleHttp\\Client;',
+      ].join('\n'),
+      init: [
+        '$client = new Client([',
+        "    'base_uri' => 'https://api.zyphr.dev/v1/',",
+        "    'headers' => [",
+        "        'X-API-Key' => getenv('ZYPHR_API_KEY'),",
+        "        'Content-Type' => 'application/json',",
+        '    ],',
+        ']);',
+      ].join('\n'),
+      fileExample: 'app/Services/ZyphrClient.php',
+    },
+    envVarsNeeded: ['ZYPHR_API_KEY'],
+    docsUrl: `${DOCS}/php`,
+    notes:
+      'There is no official Zyphr PHP SDK yet — the canonical integration uses Guzzle (or raw cURL).',
+  },
+};
+
+export function resolveInstallEntry(
+  language: SdkLanguage,
+  packageManager?: string,
+): SdkInstallEntry {
+  const entry = SDK_INSTALL_TABLE[language];
+  if (!packageManager) return entry;
+
+  const normalized = packageManager.trim().toLowerCase();
+  const match = entry.installCommands.find((c) => c.manager.toLowerCase() === normalized);
+  if (!match) return entry;
+
+  return { ...entry, installCommands: [match] };
+}

package/src/result.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ZyphrError,
+  ZyphrNotFoundError,
+  ZyphrRateLimitError,
+  ZyphrValidationError,
+} from '@zyphr-dev/node-sdk';
+import { runTool, toolResult } from './result.js';
+
+function parseTextPayload(result: { content: Array<{ type: string; text: string }> }): unknown {
+  const block = result.content[0];
+  if (!block || block.type !== 'text') throw new Error('expected text content');
+  return JSON.parse(block.text);
+}
+
+describe('toolResult', () => {
+  it('serializes success payload as JSON text content', () => {
+    const r = toolResult({ ok: true, n: 1 });
+    expect(r.content).toEqual([{ type: 'text', text: JSON.stringify({ ok: true, n: 1 }, null, 2) }]);
+  });
+});
+
+describe('runTool error rendering', () => {
+  it('passes through resolved values', async () => {
+    const r = await runTool(async () => ({ hello: 'world' }));
+    expect(r.isError).toBeUndefined();
+    expect(parseTextPayload(r)).toEqual({ hello: 'world' });
+  });
+
+  it('surfaces ZyphrNotFoundError with status + code', async () => {
+    const r = await runTool(async () => {
+      throw new ZyphrNotFoundError('The requested resource was not found');
+    });
+    expect(r.isError).toBe(true);
+    expect(parseTextPayload(r)).toEqual({
+      name: 'ZyphrNotFoundError',
+      message: 'The requested resource was not found',
+      status: 404,
+      code: 'not_found',
+    });
+  });
+
+  it('includes details + requestId on a base ZyphrError', async () => {
+    const r = await runTool(async () => {
+      throw new ZyphrError({
+        message: 'Internal explosion',
+        status: 500,
+        code: 'server_error',
+        requestId: 'req_abc123',
+        details: { hint: 'try again' },
+      });
+    });
+    expect(r.isError).toBe(true);
+    expect(parseTextPayload(r)).toEqual({
+      name: 'ZyphrError',
+      message: 'Internal explosion',
+      status: 500,
+      code: 'server_error',
+      requestId: 'req_abc123',
+      details: { hint: 'try again' },
+    });
+  });
+
+  it('surfaces validation details', async () => {
+    const r = await runTool(async () => {
+      throw new ZyphrValidationError('Missing field', { field: 'subject' });
+    });
+    expect(parseTextPayload(r)).toMatchObject({
+      name: 'ZyphrValidationError',
+      status: 422,
+      code: 'validation_error',
+      details: { field: 'subject' },
+    });
+  });
+
+  it('includes retryAfter for rate-limit errors', async () => {
+    const r = await runTool(async () => {
+      throw new ZyphrRateLimitError('Slow down', 30);
+    });
+    expect(parseTextPayload(r)).toMatchObject({
+      name: 'ZyphrRateLimitError',
+      status: 429,
+      code: 'rate_limit_exceeded',
+      retryAfter: 30,
+    });
+  });
+
+  it('falls back to {name, message} for plain Error', async () => {
+    const r = await runTool(async () => {
+      throw new Error('boom');
+    });
+    expect(parseTextPayload(r)).toEqual({ name: 'Error', message: 'boom' });
+  });
+
+  it('renders raw Response error with status + parsed body', async () => {
+    const body = { error: { message: 'Bad request', code: 'invalid_request' } };
+    const response = new Response(JSON.stringify(body), {
+      status: 400,
+      headers: { 'content-type': 'application/json' },
+    });
+    const r = await runTool(async () => {
+      // Mimic the pre-middleware shape (rare in practice).
+      throw Object.assign(new Error('Bad request'), { response });
+    });
+    expect(parseTextPayload(r)).toEqual({ status: 400, body });
+  });
+});

package/src/result.ts

@@ -0,0 +1,65 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ZyphrError, ZyphrRateLimitError } from '@zyphr-dev/node-sdk';
+
+export function toolResult(data: unknown): CallToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+export async function runTool(fn: () => Promise<unknown>): Promise<CallToolResult> {
+  try {
+    const data = await fn();
+    return toolResult(data);
+  } catch (err: unknown) {
+    return await renderApiError(err);
+  }
+}
+
+function errorPayload(content: Record<string, unknown>): CallToolResult {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify(content, null, 2) }],
+  };
+}
+
+async function renderApiError(err: unknown): Promise<CallToolResult> {
+  // Typed SDK errors — surface the full envelope so the AI can act on it.
+  if (err instanceof ZyphrError) {
+    const payload: Record<string, unknown> = {
+      name: err.name,
+      message: err.message,
+      status: err.status,
+    };
+    if (err.code) payload.code = err.code;
+    if (err.requestId) payload.requestId = err.requestId;
+    if (err.details) payload.details = err.details;
+    if (err instanceof ZyphrRateLimitError && err.retryAfter !== undefined) {
+      payload.retryAfter = err.retryAfter;
+    }
+    return errorPayload(payload);
+  }
+
+  // Raw Response error (rare — SDK middleware usually parses first).
+  if (err && typeof err === 'object' && 'response' in err) {
+    const response = (err as { response?: Response }).response;
+    if (response && typeof response.text === 'function') {
+      try {
+        const text = await response.text();
+        let parsed: unknown = text;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          /* keep raw text */
+        }
+        return errorPayload({ status: response.status, body: parsed });
+      } catch {
+        /* fall through to generic message */
+      }
+    }
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  const name = err instanceof Error ? err.name : 'Error';
+  return errorPayload({ name, message });
+}