# smithery-ai/sdk architecture

> Architecture diagram of the GitHub repository smithery-ai/sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smithery-ai/sdk
- Repository: https://github.com/smithery-ai/sdk

## Overview

##### Project type and purpose
- This is a multi-language SDK project (“Smithery SDK”) that provides both TypeScript and Python libraries to build, deploy, and interact with Model Context Protocol (MCP) servers.
- The TypeScript side is split into two NPM packages:
- “@smithery/registry” — a generated client library for discovering and calling MCP servers via an OpenAPI registry.
- “@smithery/sdk” — a toolkit to build and deploy MCP servers (includes client integrations, server runtimes, and shared utilities).
- The Python side is a PyPI package (“smithery”) offering a CLI, decorators, server support (FastMCP), plus a “scaffold” subproject for a hello_world MCP server template.

##### File structure
- Top-level:
- .github/workflows: CI/CD pipelines for publishing Python & TypeScript packages and generating SDKs from the OpenAPI spec.
- openapi/registry.yaml: the OpenAPI specification driving client codegen.
- python/: contains the Python SDK. Under python/src: smithery core modules (cli, server, utils). Under python/scaffold: a sample server template.
- typescript/registry/: generated TS client code, docs, examples, and tests for the registry package.
- typescript/sdk/: the TS SDK implementation—client integrators (OpenAI, Anthropic), transport layer, server abstractions (stateful, stateless), shared config & patches.
- Patterns:
- Code generation from OpenAPI → registry client.
- CLI layers call into core libraries.
- Separate runtime modules (client vs. server) under the SDK.

##### README for additional insights
- The README confirms the split: “Registry” (TypeScript client) and “SDK” (TypeScript & Python toolkits).
- Points to usage documentation in subdirectories.
- Purpose: simplify MCP development & deployment, and registry discovery.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "OpenAPI Spec"
        OpenAPI["OpenAPI Registry Spec"]:::external
    end

    subgraph "CI/CD Pipelines"
        CI1["publish-python.yml"]:::ci
        CI2["publish-ts.yml"]:::ci
        CI3["sdk_generation.yaml"]:::ci
        CI4["sdk_publish.yaml"]:::ci
        CI5["update-packages.yml"]:::ci
    end

    subgraph "TypeScript Registry Package"
        TSRegDir["typescript/registry/"] 
        TSRegSrc["src/"]
        TSRegIndex["index.ts"]
        TSRegFuncs["funcs/"]
        TSRegHooks["hooks/"]
        TSRegLib["lib/"]
        TSRegModels["models/"]
        TSRegDocs["docs/"]
        TSRegExamples["examples/"]
    end

    subgraph "TypeScript SDK Package"
        TSSDKDir["typescript/sdk/"]
        TSSDKIndex["src/index.ts"]
        TSSDKClient["client/"]
        TSSDKIntegrations["client/integrations/"]
        TSSDKTransport["transport.ts"]
        TSSDKServer["server/"]
        TSSDKShared["shared/"]
    end

    subgraph "Python SDK Package"
        PySDKDir["python/src/smithery/"]
        PyCLI["cli/"]
        PyServer["server/"]
        PyUtils["utils/"]
        PyDecorators["decorators.py"]
    end

    subgraph "Python Scaffold"
        PyScaffoldDir["python/scaffold/"]
        PyScaffoldProj["pyproject.toml"]
        PyScaffoldCfg["smithery.yaml"]
        PyScaffoldSrc["src/hello_server/"]
        PyScaffoldSrv["server.py"]
    end

    subgraph "External Services"
        RegistrySvc["MCP Registry Service"]:::external
        LLM["LLM Providers"]:::external
        NPM["NPM Registry"]:::external
        PyPI["PyPI"]:::external
    end

    OpenAPI --> CI3
    CI3 --> TSRegDir
    TSRegDir --> TSRegSrc
    TSRegSrc --> TSRegIndex
    TSRegSrc --> TSRegFuncs
    TSRegSrc --> TSRegHooks
    TSRegSrc --> TSRegLib
    TSRegSrc --> TSRegModels

    CI1 -->|"publish Python SDK"| PyPI
    CI2 -->|"publish TS Registry"| NPM
    CI4 -->|"publish TS SDK"| NPM
    CI5 -->|"update packages"| TSRegDir
    CI5 --> TSRegDir
    CI5 --> TSSDKDir
    CI5 --> PySDKDir

    TSRegDir -->|"runtime discover"| RegistrySvc
    TSSDKDir -->|"uses registry client"| TSRegDir
    PySDKDir -->|"uses registry client"| TSRegDir
    TSSDKDir -->|"register/discover"| RegistrySvc
    PySDKDir -->|"register/discover"| RegistrySvc

    TSSDKServer -->|"invoke LLMs"| LLM
    PyServer -->|"invoke LLMs"| LLM

    PyScaffoldSrc -->|"scaffold server w/ SDK"| PySDKDir
    PyScaffoldSrc -->|"register sample"| RegistrySvc

    class TSRegDir,TSRegSrc,TSRegIndex,TSRegFuncs,TSRegHooks,TSRegLib,TSRegModels,TSRegDocs,TSRegExamples typescript
    class TSSDKDir,TSSDKIndex,TSSDKClient,TSSDKIntegrations,TSSDKTransport,TSSDKServer,TSSDKShared typescript
    class PySDKDir,PyCLI,PyServer,PyUtils,PyDecorators python

    classDef typescript fill:#D0E8FF,stroke:#005CAF,color:#001F3F
    classDef python fill:#E8F5D0,stroke:#2E8B57,color:#004D00
    classDef external fill:#FFE0B2,stroke:#FFA500,color:#8B4513
    classDef ci fill:#F0F0F0,stroke:#A9A9A9,color:#333

    click OpenAPI "https://github.com/smithery-ai/sdk/blob/main/openapi/registry.yaml"
    click CI1 "https://github.com/smithery-ai/sdk/blob/main/.github/workflows/publish-python.yml"
    click CI2 "https://github.com/smithery-ai/sdk/blob/main/.github/workflows/publish-ts.yml"
    click CI3 "https://github.com/smithery-ai/sdk/blob/main/.github/workflows/sdk_generation.yaml"
    click CI4 "https://github.com/smithery-ai/sdk/blob/main/.github/workflows/sdk_publish.yaml"
    click CI5 "https://github.com/smithery-ai/sdk/blob/main/.github/workflows/update-packages.yml"
    click TSRegDir "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/"
    click TSRegSrc "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/src/"
    click TSRegIndex "https://github.com/smithery-ai/sdk/blob/main/typescript/registry/src/index.ts"
    click TSRegFuncs "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/src/funcs/"
    click TSRegHooks "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/src/hooks/"
    click TSRegLib "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/src/lib/"
    click TSRegModels "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/src/models/"
    click TSRegDocs "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/docs/"
    click TSRegExamples "https://github.com/smithery-ai/sdk/tree/main/typescript/registry/examples/"
    click TSSDKDir "https://github.com/smithery-ai/sdk/tree/main/typescript/sdk/"
    click TSSDKIndex "https://github.com/smithery-ai/sdk/blob/main/typescript/sdk/src/index.ts"
    click TSSDKClient "https://github.com/smithery-ai/sdk/tree/main/typescript/sdk/src/client/"
    click TSSDKIntegrations "https://github.com/smithery-ai/sdk/tree/main/typescript/sdk/src/client/integrations/"
    click TSSDKTransport "https://github.com/smithery-ai/sdk/blob/main/typescript/sdk/src/client/transport.ts"
    click TSSDKServer "https://github.com/smithery-ai/sdk/tree/main/typescript/sdk/src/server/"
    click TSSDKShared "https://github.com/smithery-ai/sdk/tree/main/typescript/sdk/src/shared/"
    click PySDKDir "https://github.com/smithery-ai/sdk/tree/main/python/src/smithery/"
    click PyCLI "https://github.com/smithery-ai/sdk/tree/main/python/src/smithery/cli/"
    click PyServer "https://github.com/smithery-ai/sdk/tree/main/python/src/smithery/server/"
    click PyUtils "https://github.com/smithery-ai/sdk/tree/main/python/src/smithery/utils/"
    click PyDecorators "https://github.com/smithery-ai/sdk/blob/main/python/src/smithery/decorators.py"
    click PyScaffoldDir "https://github.com/smithery-ai/sdk/tree/main/python/scaffold/"
    click PyScaffoldProj "https://github.com/smithery-ai/sdk/blob/main/python/scaffold/pyproject.toml"
    click PyScaffoldCfg "https://github.com/smithery-ai/sdk/blob/main/python/scaffold/smithery.yaml"
    click PyScaffoldSrc "https://github.com/smithery-ai/sdk/tree/main/python/scaffold/src/hello_server/"
    click PyScaffoldSrv "https://github.com/smithery-ai/sdk/blob/main/python/scaffold/src/hello_server/server.py"
```
