mcp-toolsets-runtime

The shared runtime for MCP Toolsets. Both developmentseed/mcp-toolsets and downstream repos generated from it install this package instead of each carrying their own copy of the runtime.

What's in here

One Python distribution (mcp-toolsets-runtime) exposing three top-level modules, plus the view-side JS bridge:

The toolset plugin contract

mcp_runtime discovers a toolset purely by convention — a <toolset>.tools module exporting:

• TOOLS — a non-empty list of LangChain tools that return a ToolResult.

• VIEWS (optional) — {tool_name: view_id}, with a built bundle at <package>/views/<view_id>.html.

• CREDENTIAL_HEADERS (optional) — header names the tools read off the transport; used to derive the model-facing auth hint.

Treat these, ToolResult, and the ui/* wire protocol as public API.

Related MCP server: @ratel-ai/mcp-server

Install

From PyPI — see the badge above for the current release:

# base: runtime + cli (lean, for tool-serving images)
pip install mcp-toolsets-runtime

# with the Chainlit web agent
pip install "mcp-toolsets-runtime[agent]"

With uv, as a consumer — an ordinary dependency, no source override:

dependencies = ["mcp-toolsets-runtime[agent]"]

Imports are unchanged from the old workspace packages: from mcp_runtime.server import build_server, etc. uv.lock pins whatever resolved, so upgrading is uv lock --upgrade-package mcp-toolsets-runtime. The package is pre-1.0, where a minor release may break — bound it at the next minor in your own pyproject.toml if you'd rather take those deliberately.

Consuming this package — the plugin contract, serving toolsets, wiring up UI views (including mcp-agent install-elements and the npm bridge), and migrating off the in-repo workspace: see docs/CONSUMING.md.

Develop

uv sync --all-extras   # install with [agent] + dev tools
./scripts/lint         # ruff check + ruff format --check + mypy (config in pyproject)
./scripts/test         # pytest
./scripts/build-js     # typecheck + build + vitest for js/mcp-view (needs node)

Releases

Versioning and CHANGELOG.md are managed by release-please from Conventional Commits. See CONTRIBUTING.md — in short, your PR title is the changelog entry, and CI fails a PR whose title isn't a valid conventional commit. The Python package and the JS bridge share one version (linked).