Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

holon

CI Go Downloads Apache 2.0 License

holon provides type-safety for MCP servers, e.g. invoking an MCP server as a function call your type checker understands.

This is currently supported via the Python SDK, TypeScript SDK and Go SDK.

Install

curl -fsSL https://holon-labs.dev/install.sh | sh

Or with Go 1.27+:

go install github.com/holon-sh/cli/cmd/holon@latest

Example

Declare dependencies under sh.holon.requires in your project's server.json (publisher-provided metadata). This example uses the public Context7 server.

{
  "name": "com.example/foo",
  "version": "0.1.0",
  "description": "Example Foo",
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "sh.holon": {
        "requires": {
          "context7": { "name": "io.github.upstash/context7", "version": "4.4.4" }
        }
      }
    }
  }
}

Generate the typed clients and type-check the calls to them.

holon types check

Or name the servers yourself. Any -s replaces the whole requires list, so server.json is not needed.

holon types check -s https://mcp.context7.com/mcp

Call the server. A wrong tool name or argument is a type error.

Python

from holon.apps import apps

await apps.context7.tools.resolve_library_id(libraryName="Next.js", query="app router")

await apps.context7.tools.resolve_library_id(libraryName=1, query="app router")
# error: Argument "libraryName" to "resolve_library_id" of "Context7Tools" has incompatible type "int"; expected "str"  [arg-type]

await apps.context7.tools.resolve_library(libraryName="Next.js", query="app router")
# error: "Context7Tools" has no attribute "resolve_library"; maybe "resolve_library_id"?  [attr-defined]

TypeScript

import { apps } from "#holon-sh";

const libraries = await apps.context7.tools["resolve-library-id"]({ libraryName: "Next.js", query: "app router" });
libraries.content; // Context7 declares no output schema, so the complete result is returned

await apps.context7.tools["resolve-library-id"]({ libraryName: 1, query: "app router" });
// error TS2322: Type 'number' is not assignable to type 'string'.

await apps.context7.tools["resolve-library-id"]({ libraryName: "Next.js" });
// error TS2741: Property '"query"' is missing in type '{ libraryName: string; }' but required in type '{ libraryName: string; query: string; }'.

await apps.context7.tools["resolve-library"]({ libraryName: "Next.js", query: "app router" });
// error TS2551: Property 'resolve-library' does not exist on type '{ readonly "query-docs": (input: { language?: string | undefined; libraryId: string; query: string; }, options?: CallOptions | undefined) => Promise<CompleteResult<unknown>>; readonly "resolve-library-id": (input: { ...; }, options?: CallOptions | undefined) => Promise<...>; }'. Did you mean 'resolve-library-id'?

Development Servers

Let's say you have a server that you're still developing, and it's not in any MCP Registry yet.

# bar/server.py
from mcp.server import MCPServer

server = MCPServer("com.example/bar", version="0.1.0", description="Example Bar")


@server.tool()
def greet(name: str) -> str:
    return f"hello {name}"

Pass its entry file with -s.

holon types check foo -s bar/server.py

Python

from holon.apps import apps

greeting = await apps.bar.tools.greet(name="world")
greeting["result"]

await apps.bar.tools.greet(name=1)
# error: Argument "name" to "greet" of "BarTools" has incompatible type "int"; expected "str"  [arg-type]

await apps.bar.tools.hello(name="world")
# error: "BarTools" has no attribute "hello"  [attr-defined]

greeting["text"]
# error: TypedDict "BarGreetOutput" has no key "text"  [typeddict-item]

TypeScript

import { apps } from "#holon-sh";

const greeting = await apps.bar.tools.greet({ name: "world" });
greeting.result;

await apps.bar.tools.greet({ name: 1 });
// error TS2322: Type 'number' is not assignable to type 'string'.

await apps.bar.tools.hello({ name: "world" });
// error TS2339: Property 'hello' does not exist on type '{ readonly greet: (input: { name: string; }, options?: CallOptions | undefined) => Promise<{ result: string; }>; }'.

greeting.text;
// error TS2339: Property 'text' does not exist on type '{ result: string; }'.

Dependencies

A dependency is an MCP server your project calls. For each one holon obtains a contract—the JSON Schemas of the server's tools and resources—and writes a typed client apps.<alias> into your project, for the SDK it declares: generated/holon-sh/ for holon-sh, generated/holon-ui/ for holon-ui, holon/apps/ for Python and holon/ for Go. TypeScript imports them as #holon-sh or #holon-ui, names holon adds to the imports of your package.json. A package that publishes code calling its clients lists generated/holon-sh in its files, so the projects that install it need not generate. holon types check then runs the language's type checker over your code against those clients. A TypeScript project needs a tsconfig.json, found as tsc finds it.

A dependency is written in one of three ways.

Source code

An implementation of an MCP server, or its parent directory.

holon types check -s bar/server.py

Registry

A sh.holon.requires entry in server.json, or -s with a registry version URL. The record is fetched for its contract.

holon types check -s https://registry.modelcontextprotocol.io/v0.1/servers/io.github.upstash%2Fcontext7/versions/4.4.4

Server

An endpoint URL. The running server is asked for tools/list and resources/list.

holon types check -s https://mcp.context7.com/mcp

If the server requires a token, name it and set <ALIAS>_MCP_TOKEN. The token is sent only to that URL's origin, as a bearer token, and is not written anywhere.

export DOCS_MCP_TOKEN=...
holon types check -s docs=https://mcp.example.com/mcp

Reference

holon types generate
Generate typed clients for MCP servers.

Leverages sh.holon.requires in the publisher-provided metadata field
(https://modelcontextprotocol.io/registry/faq#can-i-add-custom-metadata-when-publishing) to
resolve dependencies, or the -s list for explicit dependencies.

Usage:
  holon types generate [DIR] [flags]

Examples:
  # Generate for the current project
  holon types generate

  # Another project
  holon types generate ../checkout

  # Name the project's own server to call it from outside the browser too, as apps.orders
  holon types generate -s orders=./server

  # Explicit dependencies: a server directory, a server entry, an MCP registry server, a remote
  #   MCP server named docs
  holon types generate -s ../orders
  holon types generate -s ../orders/server.py
  holon types generate -s https://registry.modelcontextprotocol.io/v0.1/servers/io.github.upstash%2Fcontext7/versions/4.4.4
  holon types generate -s docs=https://mcp.context7.com/mcp

  # A remote MCP server that requires a token: DOCS_MCP_TOKEN is sent to it as a bearer token
  DOCS_MCP_TOKEN=... holon types generate -s docs=https://mcp.example.com/mcp

  # Print one server's contract, or commit it beside its server.json
  holon types generate --contract ../orders
  holon types generate --contract ../orders -o ../orders/holon-contract.json

Flags:
      --contract string      Print one server's MCP contract instead of generating
  -h, --help                 help for generate
  -o, --output string        Write the --contract document to FILE, such as holon-contract.json
  -s, --server stringArray   A dependency, [ALIAS=]PATH or URL, paths relative to the working
                             directory
  -v, --verbose              Show generation details
holon types check
Generate typed clients for MCP servers, then type-check the project's calls to them.

Leverages sh.holon.requires in the publisher-provided metadata field
(https://modelcontextprotocol.io/registry/faq#can-i-add-custom-metadata-when-publishing) to
resolve dependencies, or the -s list for explicit dependencies.

Usage:
  holon types check [DIR] [flags]

Examples:
  # Generate, then type-check
  holon types check

  # Type-check the existing clients only (no network, no writes)
  holon types check --no-generate

  # Explicit dependencies, as for generate
  holon types check -s orders=../orders

Flags:
  -h, --help                 help for check
      --no-generate          Type-check the existing clients only: no network, no install, no
                             writes
  -s, --server stringArray   A dependency, [ALIAS=]PATH or URL, paths relative to the working
                             directory

Metadata

Release files for holon-types 0.0.1.dev18

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for holon-types 0.0.1.dev18
File Actions
holon_types-0.0.1.dev18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64, Linux glibc 2.17+ x86-64 Details for holon_types-0.0.1.dev18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
holon_types-0.0.1.dev18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64, Linux glibc 2.17+ ARM64 Details for holon_types-0.0.1.dev18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
holon_types-0.0.1.dev18-py3-none-macosx_15_0_x86_64.whl Python 3 none macOS 15.0+ x86-64 Details for holon_types-0.0.1.dev18-py3-none-macosx_15_0_x86_64.whl
holon_types-0.0.1.dev18-py3-none-macosx_15_0_arm64.whl Python 3 none macOS 15.0+ ARM64 Details for holon_types-0.0.1.dev18-py3-none-macosx_15_0_arm64.whl

Total release size: 87.3 MB

Release files / holon_types-0.0.1.dev18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl

Download URL holon_types-0.0.1.dev18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
Size 22.0 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
191df33cc1f9bc306a4f5a46eee1cc1e54eb1f6aaf7ec85df44c5f24b3a027da
BLAKE2b-256 checksum
How to use checksums
54648d416704b2a2d41d94c890d618aa2c40147fe36a507e5a69619230ff4e79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / holon_types-0.0.1.dev18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl

Download URL holon_types-0.0.1.dev18-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
Size 21.1 MB
Tags Linux glibc 2.17+ ARM64 Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
84dc99582cafe5f2ca779668046291aab8c291ac4cfc617659021ac706fd2819
BLAKE2b-256 checksum
How to use checksums
31119ba8a163092600c0514b40c7d8834b2a2bf7949d0c7f718c17acc5ae4fdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / holon_types-0.0.1.dev18-py3-none-macosx_15_0_x86_64.whl

Download URL holon_types-0.0.1.dev18-py3-none-macosx_15_0_x86_64.whl
Size 22.3 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
f0e9141a7d9e37407db0aa29be1408e03b35fe32d0f88c347ee549b52cf784e5
BLAKE2b-256 checksum
How to use checksums
0ad7d2f00a82a7ac4ba8147468e66d090f5bfef8176da869fc9d892b6d93ef58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / holon_types-0.0.1.dev18-py3-none-macosx_15_0_arm64.whl

Download URL holon_types-0.0.1.dev18-py3-none-macosx_15_0_arm64.whl
Size 21.8 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
ec8f72fc60782dd2b018ea451ea910ea96cfb71aa23966506483acc116cf2f08
BLAKE2b-256 checksum
How to use checksums
935e51176532fc10d530b17c936d7450be115f3c64cc7e88109df71051cb8245
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for holon-types 0.0.1.dev18

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for holon_types-0.0.1.dev18-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page