How vercel/sdk works
Project type and purpose
• Type: A TypeScript client‐library + CLI server for the Vercel REST API
• Purpose: Provide type‐safe SDK methods and standalone functions to invoke Vercel API operations, and expose those methods as an MCP server for AI integrations
A. Code Generation Pipeline
– Speakeasy config files (.speakeasy/gen.yaml, .speakeasy/workflow.yaml)
– GitHub workflows (.github/workflows/sdk_generation.yaml, etc.)
B. Core SDK Library (TypeScript)
– src/lib: HTTP client wrapper, common utilities, retry logic
– src/core.ts + src/index.ts: SDK client entry point
– src/models: Typed data models and operation input/output definitions
– src/funcs: Standalone function implementations (one per API operation)
– src/sdk: Namespaced SDK wrapper methods (e.g. new Vercel().projects.createProject)
– src/hooks: Extension points for HTTP or registration hooks
C. MCP Server (CLI)
– src/mcp-server: CLI entry (cli.ts), server implementation (server.ts), prompts, console‐logger, extension loading
– src/mcp-server/tools: Same functions as src/funcs, but wired to accept CLI inputs/outputs
D. Documentation
– docs/models (one .md per model)
– docs/sdks (per‐resource README pages)
– Top‐level markdown (README.md, USAGE.md, FUNCTIONS.md, etc.)
E. Test Suite
– src/__tests__: TypeScript integration tests invoking both src/funcs and src/sdk
– src/__tests__/mockserver: Go‐based HTTP mock server, with its own internal handlers, logging, templates, and Dockerfile
F. CI/CD & Release
– GitHub Actions (generate SDK, run tests, publish packages)
– package.json, lockfiles, devcontainer configuration
Relationships and data flows
1. Codegen → produces src/models, src/funcs, src/sdk, src/mcp-server/tools
2. Core SDK Library calls HTTP client → Vercel API endpoints
3. Standalone functions & SDK methods use HTTP client + models
4. MCP Server wraps standalone functions, exposes them via CLI or Wire Protocol
5. Tests spin up mockserver (Go) → intercept HTTP calls from SDK to validate behavior
6. Documentation is generated from the same codegen inputs + markdown templates
7. CI workflows glue everything: trigger codegen → build → test → publish
Architectural patterns & design principles
• Code‐first, generator‐driven: Speakeasy codegen
• Layered: Models → Functions → SDK client → CLI
• Single HTTP client abstraction with hook pattern
• Tree‐shakable standalone functions for minimal bundles
• MCP server as an adapter pattern for AI tool invocation
Technologies & frameworks
• TypeScript (ESM modules)
• Node.js v20+ (HTTP, streams, Blob API)
• Go (mockserver for tests)
• Speakeasy (code generator)
• GitHub Actions (CI/CD)
• Docker (mockserver)
• Zod (optional runtime validation, peer dependency)