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 the SDK package your project declares. 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.dev16

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.dev16
File Actions
holon_types-0.0.1.dev16-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64, Linux musl 1.2+ x86-64 Details for holon_types-0.0.1.dev16-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
holon_types-0.0.1.dev16-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64, Linux musl 1.2+ ARM64 Details for holon_types-0.0.1.dev16-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
holon_types-0.0.1.dev16-py3-none-macosx_15_0_x86_64.whl Python 3 none macOS 15.0+ x86-64 Details for holon_types-0.0.1.dev16-py3-none-macosx_15_0_x86_64.whl
holon_types-0.0.1.dev16-py3-none-macosx_15_0_arm64.whl Python 3 none macOS 15.0+ ARM64 Details for holon_types-0.0.1.dev16-py3-none-macosx_15_0_arm64.whl

Total release size: 87.2 MB

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

Download URL holon_types-0.0.1.dev16-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
3098ee007614c453090277df1ea3d98c096c75ed316247e86d165d7ca569d2a8
BLAKE2b-256 checksum
How to use checksums
ee7aac5472d8d2f522359cafd83308c719d70ce29c47d4035a2f8143b424f355
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 8, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev16-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
07b68ee3307241807fd54e6c9f00d124499efdec1ec9cdbbc1d201b74e0afe01
BLAKE2b-256 checksum
How to use checksums
cec0ac2246cf82a08400e19ba509de314685d6e17e19965e457d83fe03e805aa
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 8, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev16-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
f4016f3af3d490c4aea5140ca36ae5a7bdac86da238d204c30977bee715bc33a
BLAKE2b-256 checksum
How to use checksums
cec094097b9b9c649d548384f872bb52a6b397acffcf02ddb766e0b9d16d103a
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 8, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev16-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
a6f72e9e4f48c7361b00f25f3eeb31c5d7b423843d896e4cc88d2c55ed3e2009
BLAKE2b-256 checksum
How to use checksums
630543889bed0761012d1702d7583c0fa1358e69e85f4014ffdbcb9a19567bf3
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 8, 2026.

Transparency log

Security for holon-types 0.0.1.dev16

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.dev16-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 8, 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