Bridge bobrapet Stories to Model Context Protocol (MCP) servers. The MCP Adapter Engram hides JSON-RPC wiring, transport fan-out, and Kubernetes plumbing so your workflows can invoke external MCP providers or in-cluster MCP services with a simple with: block.

• Two transport modes – Connect to remote MCP servers over Streamable HTTP/S, or spin up one-off stdio Pods with automatic cleanup.
• Protocol fidelity – Raw MCP responses flow back under output.data.result without reshaping, preserving the MCP schema.
• Secure secret handling – The stdio runner receives only the server secret bucket; optionally materialized as a short-lived Secret with stdio.useEphemeralSecret.
• Cleanup aware – Owner references and a two-hour reaper prevent orphan runner Pods.
• Enriched observability – SDK patches include manifest snapshots (object counts, sizes) and latch onto bobrapet metrics/logging.

┌──────────────┐     ┌─────────────────────────┐      ┌──────────────────┐
│ Story (step) │───▶ │ MCP Adapter Engram Pod  │────▶ │ MCP transport     │
└──────────────┘     │  - loads StepRun env    │      │  • HTTP endpoint  │
                     │  - establishes session  │      │  • stdio runner   │
                     │  - forwards JSON-RPC    │◀─────│  • SSE stream     │
                     └─────────────────────────┘      └──────────────────┘

make lint
go test ./...
make docker-build

Apply Engram.yaml and point your Story step at the mcp-adapter template. Example (stdio transport):

apiVersion: bubustack.io/v1alpha1
kind: Engram
metadata:
  name: mcp-github-batch
spec:
  templateRef:
    name: mcp-adapter
  mode: job
  with:
    transport: "stdio"
    stdio:
      image: ghcr.io/github/mcp-server:latest
      deletionPolicy: DeleteOnFinish
    mcp:
      initClientCapabilities: {}
  secrets:
    server: github-mcp-secrets

• GitHub MCP registry: https://github.com/modelcontextprotocol/registry
• Cursor MCP directory: https://cursor.directory/mcp
• Docker Hub (search for MCP servers): https://hub.docker.com/search?q=mcp
• https://mcpservers.org/remote-mcp-servers = https://mcp.so/
• https://mcpmarket.com/
• https://mcpservers.org/
• GHCR listing for this engram: https://ghcr.io/bubustack/mcp-adapter-engram

The Engram expects the following inputs, decoded into the Inputs struct:

Batch mode returns map[string]any{"data": {...}} where:

Streaming mode emits each response as a StreamMessage with the JSON response in Payload and the same bytes mirrored into Binary with MimeType: application/json.

• streamable_http
  • Minimal footprint—no extra Pods.
  • Adds Mcp-Session-Id header automatically and merges server.headers + secrets.
  • Supports long-lived sessions using JSON polling or SSE.
• stdio
  • Spins up a dedicated runner Pod per Engram instance.
  • Uses SPDY pods/attach to stream MCP JSON-RPC over stdin/stdout.
  • stdio.useEphemeralSecret=true creates a short-lived per-run Secret for server credentials.

• make lint – Validate code with golangci-lint.
• go test ./... – Run unit tests (no cluster required).
• make run – Start the adapter locally (requires bobrapet env vars + kubeconfig).
• make docker-build – Multi-arch image build via docker buildx.

• Contributing
• Support
• Security Policy
• Code of Conduct
• Discord

Copyright 2025 BubuStack.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.