Manifest MCP

MCP servers for Manifest Network and Cosmos SDK chains.

Exposes on-chain queries and transactions as Model Context Protocol tools, so any MCP-compatible client (Claude Desktop, Cursor, etc.) can interact with the blockchain through natural language.

Monorepo structure

packages/
  core/      @manifest-network/manifest-mcp-core      Shared library: Cosmos logic, on-chain tool functions, server utilities
  chain/     @manifest-network/manifest-mcp-chain     MCP server for chain operations (6 tools, +1 optional faucet)
  lease/     @manifest-network/manifest-mcp-lease     MCP server for on-chain lease operations (8 tools)
  fred/      @manifest-network/manifest-mcp-fred      MCP server for provider/Fred operations (11 tools)
  cosmwasm/  @manifest-network/manifest-mcp-cosmwasm  MCP server for MFX-to-PWR converter (2 tools)
  node/      @manifest-network/manifest-mcp-node      CLI entry points + encrypted keyfile wallet

Dependency direction: node -> {chain, lease, fred, cosmwasm} -> core (never reverse).

Prerequisites

• Node.js >= 20
• npm >= 9 (ships with Node 20+)

Quick start

# Install dependencies
npm install

# Build all packages
npm run build

# Generate an encrypted wallet keyfile (interactive)
npx manifest-mcp-chain keygen

See packages/node/README.md for wallet setup and MCP client integration.

MCP tools

Chain server (manifest-mcp-chain) -- 6 tools (+1 optional)

Lease server (manifest-mcp-lease) -- 8 tools

Fred server (manifest-mcp-fred) -- 11 tools

The Fred server also exposes 3 MCP resources (manifest://leases/active, manifest://leases/recent, manifest://providers) and 3 prompts (deploy-containerized-app, diagnose-failing-app, shutdown-all-leases).

CosmWasm server (manifest-mcp-cosmwasm) -- 2 tools

Supported modules: bank, staking, distribution, gov, billing, sku, group, wasm, poa, tokenfactory, ibc-transfer, authz, feegrant, auth (query only), mint (query only), manifest (tx only).

Documentation

Development

For a deeper look at the codebase design, see ARCHITECTURE.md.

# Build all packages
npm run build

# Lint (type-check)
npm run lint

# Run unit tests
npm run test

# Run E2E tests (requires Docker)
docker compose -f e2e/docker-compose.yml up -d --wait --wait-timeout 180
npm run test:e2e
docker compose -f e2e/docker-compose.yml down -v --remove-orphans

# Code formatting and import sorting (Biome)
npm run check        # check only
npm run check:fix    # auto-fix

Adding a new module

1. Create a query handler in packages/core/src/queries/<module>.ts implementing routeXxxQuery()
2. Create a transaction handler in packages/core/src/transactions/<module>.ts implementing routeXxxTransaction()
3. Register both in the QUERY_MODULES / TX_MODULES maps in packages/core/src/modules.ts

The module is then automatically available through the cosmos_query and cosmos_tx tools, and discoverable via list_modules and list_module_subcommands.

Releasing

All six packages are versioned in lockstep and published together.

Setup (one-time)

The release workflow uses npm OIDC trusted publishing (provenance). No npm token is needed as a repository secret -- authentication is handled automatically via GitHub's OIDC identity provider. Ensure the npm package is linked to the repository for provenance to work.

Publishing a release

# 1. Bump versions (updates all package.json files and syncs the lockfile)
npm run release:version -- 0.2.0

# 2. Commit and tag
git add -A
git commit -m "chore: release v0.2.0"
git tag v0.2.0

# 3. Push (triggers the release workflow)
git push origin main --tags

Pushing a vMAJOR.MINOR.PATCH tag triggers the Release workflow, which:

1. Validates the tag version matches all package.json files
2. Builds, type-checks, runs Biome checks, and tests
3. Publishes all packages to npm (with provenance) in dependency order: core → chain → lease → fred → cosmwasm → node
4. Creates a GitHub Release with auto-generated notes (best-effort — publish succeeds even if this fails)

License

MIT