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://holon-labs.dev/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 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 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 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; }'.

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

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

Total release size: 87.5 MB

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

Download URL holon_types-0.0.1.dev20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
Size 22.1 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
f8ea065a0824799004b6aeb2d255f4013e8eda0ce7717f0dae43864f74f87e6d
BLAKE2b-256 checksum
How to use checksums
cf6b95cc37bbf775c5c58bf7647c6ae29fa3ca020f50b0d272255b6b3911c71d
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.dev20-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl

Download URL holon_types-0.0.1.dev20-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
02e0c635269ceeb6b713a7e29db69f0abfacdd16a714de9eeade5cdaf5bec0fb
BLAKE2b-256 checksum
How to use checksums
34ef40ab5fb931821c7a2922add1219d3cb3927d786e2493795460266662ae22
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.dev20-py3-none-macosx_15_0_x86_64.whl

Download URL holon_types-0.0.1.dev20-py3-none-macosx_15_0_x86_64.whl
Size 22.4 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
9031d92f32c37713ea6eb994ee9593f57c2671f82f1d007ac68948836952661f
BLAKE2b-256 checksum
How to use checksums
e035f5b6a068a1c6eaa75c9c27bd061b38d461a6046795838f08318416071a10
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.dev20-py3-none-macosx_15_0_arm64.whl

Download URL holon_types-0.0.1.dev20-py3-none-macosx_15_0_arm64.whl
Size 21.9 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
418eb861598d0fdb7f54c7d0f3672467f86df7ae1593efc418460c5b286b48bf
BLAKE2b-256 checksum
How to use checksums
8e81fff45177521f9ca1f1f4b4b0ab2c82827808fac868fd5fe6751c1aa5c9d7
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.dev20

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