Skip to main content
Pre-release

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

holon

CI Docs Go Apache 2.0 License Discord

holon is a framework for type-safe MCP servers.

Install

curl -fsSL https://holonlabs.ai/install.sh | sh

Example

Create an app

holon init foo --lang py  # python
holon init foo --lang ts  # typescript

Dependencies

Declare dependencies under sh.holon.requires in a server.json beside the server (publisher-provided metadata). This example uses the public Hugging Face MCP server.

{
  "name": "com.example/foo",
  "version": "0.1.0",
  "description": "Example Foo",
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "sh.holon": {
        "requires": {
          "huggingface": { "url": "https://huggingface.co/mcp" }
        }
      }
    }
  }
}

Types

Generate the typed clients, then type-check the calls to them. holon types check only reads, so it also runs beside holon dev, which keeps the clients current.

holon types generate
holon types check

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

holon types generate -s huggingface=https://huggingface.co/mcp

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

Python

from holon.apps import apps

await apps.huggingface.tools.hub_repo_search(query="llama")

await apps.huggingface.tools.hub_repo_search(limit="3")
# error: Argument "limit" to "hub_repo_search" of "HuggingfaceTools" has incompatible type "str"; expected "float"  [arg-type]

await apps.huggingface.tools.hub_repo_details()
# error: Missing named argument "repo_ids" for "hub_repo_details" of "HuggingfaceTools"  [call-arg]

await apps.huggingface.tools.hub_search(query="llama")
# error: "HuggingfaceTools" has no attribute "hub_search"; maybe "hub_repo_search"?  [attr-defined]

TypeScript

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

await apps.huggingface.tools.hub_repo_search({ query: "llama" });

await apps.huggingface.tools.hub_repo_search({ limit: "3" });
// error TS2322: Type 'string' is not assignable to type 'number'.

await apps.huggingface.tools.hub_repo_details({});
// error TS2741: Property '"repo_ids"' is missing in type '{}' but required in type '{ config?: string | undefined; limit?: number | undefined; offset?: number | undefined; operations?: ("dataset_preview" | "dataset_structure" | "overview")[] | undefined; repo_ids: string[]; repo_type?: "dataset" | ... 2 more ... | undefined; split?: string | undefined; }'.

await apps.huggingface.tools.hub_search({ query: "llama" });
// error TS2339: Property 'hub_search' does not exist on type '{ readonly hf_fs: (input: { operations: { args: string[]; cmd: "attach" | "cat" | "find" | "ls" | "search" | "stat"; }[]; }, options?: ToolCallOptions | undefined) => Promise<{ results: ({ ...; } | { ...; })[]; truncated?: boolean | undefined; truncation_reason?: "output_budget" | undefined; }>; readonly hf_whoami: ...'.

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 generate foo -s bar/server.py
holon types check foo

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; }'.

Community

Ask questions and share what you're building on the Holon Discord.

Reference

See the CLI reference.

Metadata

Release files for holon-types 0.0.1.dev36

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

Total release size: 89.0 MB

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

Download URL holon_types-0.0.1.dev36-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
Size 22.5 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
2b1d9a20dcae9847d2e056634dfe868314129f0706857e39278039b7f58556c5
BLAKE2b-256 checksum
How to use checksums
1e2b9d2a78afe56783b13563e8b0a1f17f787ab8a55224b3a69e6f0aa6837c93
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 13, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev36-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
Size 21.5 MB
Tags Linux glibc 2.17+ ARM64 Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
4fe37b04aa5578092c624ca672dfbaf205447065cd828fbe4c4348ce0366f327
BLAKE2b-256 checksum
How to use checksums
27b0aff4f1541bb1301d718afe644c51de81f51449c4657d48fe7563ec3aeaaf
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 12, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev36-py3-none-macosx_15_0_x86_64.whl
Size 22.8 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
0f03cbfb3cd629eeaed6c6c70e0acdba1964bfa021574d19d5fd9abb10663e27
BLAKE2b-256 checksum
How to use checksums
ba28ac54314f0130eb2e11ff302ebfa0482cc792e41ca5d3d4c6ccb550e56ce3
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 12, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev36-py3-none-macosx_15_0_arm64.whl
Size 22.3 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
dd7e834c0757ebf745ed8e6af013ea0376d3fa2b0a405d8cd9eece78c96f8e70
BLAKE2b-256 checksum
How to use checksums
1ba880dc1fb50181aa7dd70d428eaf1ff2c70e93ec636b2517dd073e70603ac3
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 12, 2026.

Transparency log

Security for holon-types 0.0.1.dev36

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.dev36-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 13, 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