README
¶
loom-mcp
loom-mcp is the home for the agent, MCP, and registry framework in this repository.
It combines:
- a Loom-powered design DSL for describing agents, toolsets, MCP servers, and registries,
- code generation driven by
github.com/CaliLuke/loom, - a runtime for planning, execution, streaming, memory, and durable workflows.
Current status
This repository has been rehomed and detached from the original fork network to prepare for a fresh release line.
Two facts are important right now:
- The repository name is
loom-mcp. - The Go module path is
github.com/CaliLuke/loom-mcp.
Repo identity and module identity are now aligned.
What lives here
design/: design source of truth.dsl/: agent, MCP, and registry DSL.codegen/: generators for agents, MCP adapters, codecs, and registries.runtime/: execution runtime, planners, engines, MCP callers, and streaming.registry/: registry service implementation and generated transports.docs/: in-repo technical documentation.quickstart/: runnable starter project and generated walkthrough material.
Dependencies
This repo currently targets:
github.com/CaliLuke/loom v1.0.2- Go
1.25.5
The standard CLI for generation is:
go install github.com/CaliLuke/loom/cmd/loom@v1.0.2
Working in this repo
Common commands:
make goa-status
make goa-local
make goa-remote
make regen-assistant-fixture
make verify-mcp-local
make lint
make test
make itest
Design changes should always start in design/*.go. Regenerate after changing the DSL and do not hand-edit generated gen/ files.
Documentation
Start here:
Release prep note
This repo has intentionally been reset to a clean branch/repository identity. Old branch structure and inherited tags have been removed, and the next published tag should start the new loom-mcp release line.
License
MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package boundedresult defines the canonical bounded-result contract shared by DSL validation, code generation, and runtime projection.
|
Package boundedresult defines the canonical bounded-result contract shared by DSL validation, code generation, and runtime projection. |
|
codegen
|
|
|
agent
Package codegen isolates runtime policy artifacts from structural generator data assembly.
|
Package codegen isolates runtime policy artifacts from structural generator data assembly. |
|
agent/tests/testscenarios
Package testscenarios provides reusable Goa design scenarios for testing agent code generation.
|
Package testscenarios provides reusable Goa design scenarios for testing agent code generation. |
|
ir
Package ir provides a stable, deterministic intermediate representation (IR) used as the sole input to loom-mcp code generation templates.
|
Package ir provides a stable, deterministic intermediate representation (IR) used as the sole input to loom-mcp code generation templates. |
|
mcp
Package codegen contains the MCP generator built on top of Goa evaluation and Goa's JSON-RPC codegen.
|
Package codegen contains the MCP generator built on top of Goa evaluation and Goa's JSON-RPC codegen. |
|
naming
Package naming contains shared naming helpers used by loom-mcp code generators.
|
Package naming contains shared naming helpers used by loom-mcp code generators. |
|
shared
Package shared provides common infrastructure for protocol code generation shared between MCP implementations.
|
Package shared provides common infrastructure for protocol code generation shared between MCP implementations. |
|
testhelpers
Package testhelpers provides shared test utilities for codegen packages.
|
Package testhelpers provides shared test utilities for codegen packages. |
|
Package dsl provides the loom-mcp design-time DSL for declaring agents, toolsets, MCP servers, registries, and run policies.
|
Package dsl provides the loom-mcp design-time DSL for declaring agents, toolsets, MCP servers, registries, and run policies. |
|
expr
|
|
|
agent
Package agent defines the expression types used to represent agent and toolset declarations during Goa design evaluation.
|
Package agent defines the expression types used to represent agent and toolset declarations during Goa design evaluation. |
|
mcp
Package mcp defines the expression types used to represent MCP server configuration during Goa design evaluation.
|
Package mcp defines the expression types used to represent MCP server configuration during Goa design evaluation. |
|
Package features houses optional integrations that plug into loom-mcp agents.
|
Package features houses optional integrations that plug into loom-mcp agents. |
|
memory/mongo
Package mongo registers MongoDB-backed memory storage for loom-mcp agents.
|
Package mongo registers MongoDB-backed memory storage for loom-mcp agents. |
|
memory/mongo/clients/mongo
Package mongo implements the low-level MongoDB client used by the memory store.
|
Package mongo implements the low-level MongoDB client used by the memory store. |
|
model/anthropic
Package anthropic provides a model.Client implementation backed by the Anthropic Claude Messages API.
|
Package anthropic provides a model.Client implementation backed by the Anthropic Claude Messages API. |
|
model/bedrock
Package bedrock provides a model.Client implementation backed by the AWS Bedrock Converse API.
|
Package bedrock provides a model.Client implementation backed by the AWS Bedrock Converse API. |
|
model/gateway
Package gateway provides a transport-agnostic server and client wrapper for model completion.
|
Package gateway provides a transport-agnostic server and client wrapper for model completion. |
|
model/middleware
Package middleware provides reusable model.Client middlewares such as adaptive rate limiting.
|
Package middleware provides reusable model.Client middlewares such as adaptive rate limiting. |
|
model/openai
Package openai provides a model.Client implementation backed by the OpenAI Chat Completions API.
|
Package openai provides a model.Client implementation backed by the OpenAI Chat Completions API. |
|
mongo/clientinfra
Package clientinfra provides shared Mongo client setup helpers.
|
Package clientinfra provides shared Mongo client setup helpers. |
|
policy/basic
Package basic provides a simple policy.Engine implementation that enforces optional allow/block lists and honors planner retry hints.
|
Package basic provides a simple policy.Engine implementation that enforces optional allow/block lists and honors planner retry hints. |
|
prompt/mongo
Package mongo provides a MongoDB-backed implementation of the runtime prompt store.
|
Package mongo provides a MongoDB-backed implementation of the runtime prompt store. |
|
prompt/mongo/clients/mongo
Package mongo implements the low-level MongoDB client used by the prompt override store.
|
Package mongo implements the low-level MongoDB client used by the prompt override store. |
|
runlog/mongo
Package mongo registers MongoDB-backed run event log storage for loom-mcp agents.
|
Package mongo registers MongoDB-backed run event log storage for loom-mcp agents. |
|
runlog/mongo/clients/mongo
Package mongo implements the low-level MongoDB client used by the run log store.
|
Package mongo implements the low-level MongoDB client used by the run log store. |
|
session/mongo
Package mongo provides a MongoDB-backed implementation of the agents runtime session store.
|
Package mongo provides a MongoDB-backed implementation of the agents runtime session store. |
|
session/mongo/clients/mongo
Package mongo hosts the MongoDB client used by the session store.
|
Package mongo hosts the MongoDB client used by the session store. |
|
stream/pulse
Package pulse exposes a stream.Sink implementation that publishes runtime events to goa.design/pulse streams.
|
Package pulse exposes a stream.Sink implementation that publishes runtime events to goa.design/pulse streams. |
|
stream/pulse/clients/pulse
Package pulse provides a thin loom-mcp specific wrapper around Pulse streams.
|
Package pulse provides a thin loom-mcp specific wrapper around Pulse streams. |
|
integration_tests
|
|
|
framework
Package framework provides a lightweight scenario runner used by the integration tests to launch the example server and exercise MCP scenarios.
|
Package framework provides a lightweight scenario runner used by the integration tests to launch the example server and exercise MCP scenarios. |
|
internal
|
|
|
upstreampaths
Package upstreampaths centralizes upstream module/import constants used by codegen and tests.
|
Package upstreampaths centralizes upstream module/import constants used by codegen and tests. |
|
Package registry owns the toolset catalog used by the gateway.
|
Package registry owns the toolset catalog used by the gateway. |
|
cmd/registry
command
Command registry runs the internal tool registry gRPC server.
|
Command registry runs the internal tool registry gRPC server. |
|
design
Package design defines the internal tool registry service using Goa DSL.
|
Package design defines the internal tool registry service using Goa DSL. |
|
runtime
|
|
|
agent
Package agent provides strong type identifiers for agents and tools.
|
Package agent provides strong type identifiers for agents and tools. |
|
agent/api
Package api defines shared types that cross workflow/activity boundaries in the agent runtime.
|
Package api defines shared types that cross workflow/activity boundaries in the agent runtime. |
|
agent/engine
Package engine defines workflow engine abstractions for durable agent execution.
|
Package engine defines workflow engine abstractions for durable agent execution. |
|
agent/engine/inmem
Package inmem provides an in-memory workflow engine implementation for tests and local development.
|
Package inmem provides an in-memory workflow engine implementation for tests and local development. |
|
agent/engine/temporal
Package temporal implements the loom-mcp workflow engine adapter backed by Temporal (https://temporal.io).
|
Package temporal implements the loom-mcp workflow engine adapter backed by Temporal (https://temporal.io). |
|
agent/hooks
Package hooks implements fan-out hooks for runtime observability and memory.
|
Package hooks implements fan-out hooks for runtime observability and memory. |
|
agent/interrupt
Package interrupt provides workflow signal handling for pausing and resuming agent runs.
|
Package interrupt provides workflow signal handling for pausing and resuming agent runs. |
|
agent/memory
Package memory persists event payloads as generic maps so stores can serialize them uniformly, but runtime and transcript code should interact with the typed payload structs in this file.
|
Package memory persists event payloads as generic maps so stores can serialize them uniformly, but runtime and transcript code should interact with the typed payload structs in this file. |
|
agent/memory/inmem
Package inmem provides an in-memory implementation of memory.Store for testing and local development.
|
Package inmem provides an in-memory implementation of memory.Store for testing and local development. |
|
agent/model
Package model defines JSON helpers for marshaling and unmarshaling provider message parts.
|
Package model defines JSON helpers for marshaling and unmarshaling provider message parts. |
|
agent/planner
Package planner defines planner contracts and helper implementations.
|
Package planner defines planner contracts and helper implementations. |
|
agent/policy
Package policy codifies policy evaluation and enforcement for agent runs.
|
Package policy codifies policy evaluation and enforcement for agent runs. |
|
agent/prompt
Package prompt contains runtime prompt registry and override resolution logic.
|
Package prompt contains runtime prompt registry and override resolution logic. |
|
agent/rawjson
Package rawjson provides a safe raw JSON byte type for workflow boundaries.
|
Package rawjson provides a safe raw JSON byte type for workflow boundaries. |
|
agent/reminder
Package reminder defines core types for run-scoped system reminders used to provide backstage guidance to planners (safety, correctness, workflow, and context hints).
|
Package reminder defines core types for run-scoped system reminders used to provide backstage guidance to planners (safety, correctness, workflow, and context hints). |
|
agent/run
Package run defines primitives for tracking agent run executions.
|
Package run defines primitives for tracking agent run executions. |
|
agent/runlog
Package runlog provides a durable, append-only event log for agent runs.
|
Package runlog provides a durable, append-only event log for agent runs. |
|
agent/runlog/inmem
Package inmem provides an in-memory implementation of runlog.Store.
|
Package inmem provides an in-memory implementation of runlog.Store. |
|
agent/runtime
Package runtime emits cooperative activity heartbeats for long-running planner and tool activities so engine-driven cancellation reaches streaming provider calls promptly instead of after the activity returns on its own.
|
Package runtime emits cooperative activity heartbeats for long-running planner and tool activities so engine-driven cancellation reaches streaming provider calls promptly instead of after the activity returns on its own. |
|
agent/runtime/hints
Package hints provides lightweight, template-based rendering helpers for tool call/result hints.
|
Package hints provides lightweight, template-based rendering helpers for tool call/result hints. |
|
agent/session
Package session defines durable session lifecycle and run metadata primitives.
|
Package session defines durable session lifecycle and run metadata primitives. |
|
agent/session/inmem
Package inmem provides an in-memory implementation of session.Store.
|
Package inmem provides an in-memory implementation of session.Store. |
|
agent/stream
Package stream provides abstractions for delivering real-time agent execution updates to clients.
|
Package stream provides abstractions for delivering real-time agent execution updates to clients. |
|
agent/stream/bridge
Package bridge provides a discoverable entrypoint to wire the runtime hook bus to a stream.Sink without importing the hooks subscriber directly.
|
Package bridge provides a discoverable entrypoint to wire the runtime hook bus to a stream.Sink without importing the hooks subscriber directly. |
|
agent/telemetry
Package telemetry integrates runtime events with Clue tracing and metrics.
|
Package telemetry integrates runtime events with Clue tracing and metrics. |
|
agent/toolerrors
Package toolerrors provides structured error types for tool invocation failures.
|
Package toolerrors provides structured error types for tool invocation failures. |
|
agent/tools
Package tools defines runtime-facing tool metadata and helpers.
|
Package tools defines runtime-facing tool metadata and helpers. |
|
agent/transcript
Package transcript provides a minimal, provider‑precise ledger that records the canonical conversation needed to rebuild provider payloads (e.g., Bedrock) without leaking provider SDK types into workflow state.
|
Package transcript provides a minimal, provider‑precise ledger that records the canonical conversation needed to rebuild provider payloads (e.g., Bedrock) without leaking provider SDK types into workflow state. |
|
mcp
Package mcp provides runtime MCP transport callers, normalization helpers, and support utilities used by generated MCP adapters.
|
Package mcp provides runtime MCP transport callers, normalization helpers, and support utilities used by generated MCP adapters. |
|
mcp/retry
Package retry defines shared types and helpers for producing standardized retryable errors and compact repair prompts used across generated clients.
|
Package retry defines shared types and helpers for producing standardized retryable errors and compact repair prompts used across generated clients. |
|
registry
Package registry provides client-side components for agents to consume the internal tool registry.
|
Package registry provides client-side components for agents to consume the internal tool registry. |
|
temporaltrace
Package temporaltrace defines the OpenTelemetry tracing contract for Temporal activity execution in loom-mcp powered runtimes.
|
Package temporaltrace defines the OpenTelemetry tracing contract for Temporal activity execution in loom-mcp powered runtimes. |
|
toolregistry
Package toolregistry defines the canonical wire protocol and stream naming helpers used by the tool registry gateway and tool providers/consumers.
|
Package toolregistry defines the canonical wire protocol and stream naming helpers used by the tool registry gateway and tool providers/consumers. |
|
toolregistry/executor
Package executor provides registry-backed tool execution.
|
Package executor provides registry-backed tool execution. |
|
toolregistry/provider
Package provider implements the provider-side Pulse subscription loop for registry-routed tool execution.
|
Package provider implements the provider-side Pulse subscription loop for registry-routed tool execution. |
|
Package testutil provides utilities for golden file testing.
|
Package testutil provides utilities for golden file testing. |
Click to show internal directories.
Click to hide internal directories.