Skip to main content
Loss of provenance

A previous release had provenance metadata, but this release does not. View details.

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

Create an app

holon init orders --lang py

--lang ts writes the server in TypeScript instead, and --lang go in Go. Each app has an MCP server with one tool, greet, and a view the server returns as an MCP App and Holon serves as a page. The view calls the tool through a typed client:

// orders/ui/main.ts
const { result } = await server.tools.greet({ name: name.value });

holon init pins the newest Holon SDK releases (on npm, those that read the clients it writes), installs the dependencies (uv for Python, go get for Go, the project's package manager for Node.js), generates the clients, and adds the app to holon.yaml. holon types check then type-checks the server and the view. A Go server's contract isn't read from its source, so its view calls greet untyped, and go build type-checks the server. Run the app with holon dev.

In an existing Go module, Python project or Node.js project, holon init adds the server and the view beside the project's files, and the dependencies to its go.mod, pyproject.toml or package.json:

cd billing
holon init

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 init
Create an app in DIR, or the working directory: an MCP server in Go, Python or TypeScript, and a
view it serves as an MCP App and as a page. The app is named after DIR.

In an empty or absent DIR, holon init writes a new project. In a Go module (go.mod), a Python
project (pyproject.toml) or a Node.js project (package.json), it adds the server and the view beside
the project's own files: Go and Python dependencies through go get and uv, npm packages into
package.json, and lines to .gitignore. It leaves the project's scripts and tsconfig.json as written.

holon init pins the newest Holon SDK releases, on npm those that read the clients this holon writes,
installs the dependencies, generates the clients, and adds the app to the working directory's
holon.yaml when DIR is inside it, or else to DIR's.

Usage:
  holon init [DIR] [flags]

Examples:
  # A Go app in ./orders
  holon init orders --lang go

  # A Python app in ./orders
  holon init orders --lang py

  # A TypeScript app in the working directory, with its MCP server name
  holon init --lang ts --name io.github.acme/orders

  # Add an app to the Python project in the working directory
  holon init

Flags:
  -h, --help          help for init
      --lang string   The server's language: go, py or ts; detected in an existing project
      --name string   The MCP server name (default com.example/APP)
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.dev19

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

Loss of provenance

These files do not have provenance metadata, despite files in a prior release including this data.

We recommend further investigation before installing these files. View details.

Built distributions (wheels)

Table of built distributions (wheels) for holon-types 0.0.1.dev19
File Actions
holon_types-0.0.1.dev19-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.dev19-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.musllinux_1_2_x86_64.whl
holon_types-0.0.1.dev19-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.dev19-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_2_aarch64.whl
holon_types-0.0.1.dev19-py3-none-macosx_15_0_x86_64.whl Python 3 none macOS 15.0+ x86-64 Details for holon_types-0.0.1.dev19-py3-none-macosx_15_0_x86_64.whl
holon_types-0.0.1.dev19-py3-none-macosx_15_0_arm64.whl Python 3 none macOS 15.0+ ARM64 Details for holon_types-0.0.1.dev19-py3-none-macosx_15_0_arm64.whl

Total release size: 87.5 MB

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

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL holon_types-0.0.1.dev19-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
01e1f7a31f4d3e2a21b800e210abbfbc4f0d6433e88455e00a0da46afb96fc3c
BLAKE2b-256 checksum
How to use checksums
f590f8eee2afff2e951d102b75899cd4d45c171743deaed8e97d7c1019ffb58d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

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

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL holon_types-0.0.1.dev19-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
7f17f82638e102e3d2b852b74fe1439fc606bc95b2582ec70af2fb94f0829d57
BLAKE2b-256 checksum
How to use checksums
346f5facbbdd6e3d374bb82e6aeca7ddb96ecd147735b2ecf583690260bc08bb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

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

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL holon_types-0.0.1.dev19-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
2a710024efa727edff77c30ebeb1e1c6058875d78102028e43084d5ecbe92035
BLAKE2b-256 checksum
How to use checksums
55e11227788db076e4cf2e7f0ffd3b6df2f7a60b3d3a0e7942e9d52a448ae767
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

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

Loss of provenance

This file belongs to a release without provenance metadata, despite a prior release including this data.

We recommend further investigation before installing this file. View details.

Download URL holon_types-0.0.1.dev19-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
f1e2d1f3f64021ce109f2b97c6c5f7df77d7c908765e71dea2a075e71f13c91e
BLAKE2b-256 checksum
How to use checksums
ed943012614e00733c3e78a07001e421301d529a4c1208688771f08a87298d9a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for holon-types 0.0.1.dev19

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.

Loss of provenance

A previous release of these files had provenance metadata, but this release does not.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Release comparison

  • Removed 0.0.1.dev18 4 files With provenance
  • Added 0.0.1.dev19 4 files Without provenance

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