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.dev54

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

Total release size: 88.0 MB

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

Download URL holon_types-0.0.1.dev54-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
Size 22.2 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
6fb8387ed597ebde28092305df2555f40d1afa2ede5490332f3ae20c02485f85
BLAKE2b-256 checksum
How to use checksums
6a9e4d25f10cef2868c3199adaa1527722c1dca3d40d1808fbc20a8e9cbfac8d
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 16, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev54-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
Size 21.3 MB
Tags Linux glibc 2.17+ ARM64 Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
caf1fc2f3dbfb3365242691c2ec262fe58f4af58fe3482a1f2453535409253a8
BLAKE2b-256 checksum
How to use checksums
6ddbca161149ea37fa3e27af10072174740a487587590b18f131ce578467bf5c
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 16, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev54-py3-none-macosx_15_0_x86_64.whl
Size 22.5 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
04680cd85fb7481e404bc863726701acb778ec614e6087226b16e7fed84a9878
BLAKE2b-256 checksum
How to use checksums
a48431c56354247497144e1f16c04e88e2d095d25756c220809a78067e3562bd
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 16, 2026.

Transparency log

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

Download URL holon_types-0.0.1.dev54-py3-none-macosx_15_0_arm64.whl
Size 22.0 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
31d14da270738ec47152fab7146d3ed20d04a8f76bbe6da47dd56880ad7188ab
BLAKE2b-256 checksum
How to use checksums
b2c448b8a4fadc8c9e584ddf70c8229ae1d1e5950394e6088a10ed32578ec2b3
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 16, 2026.

Transparency log

Security for holon-types 0.0.1.dev54

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.dev54-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 16, 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