Skip to main content
Glama

semula

A mock LLM server powered by your AI subscription. Instead of paying for an expensive LLM API, point your app at semula and let the Claude Code or Codex subscription you already have write the answers. semula serves an OpenAI-compatible endpoint, and your coding agent is the model behind it. As a bonus it records each answer and replays it instantly, offline, for free.

The Pending screen: parked calls, one selected, an answer typed in

0.x. semula works end to end and the tests are broad, but a minor release may still change behaviour. The changelog lists every change, and recordings made with one release open in the next.

Why

A paid LLM API bills every call, and development and test runs make a lot of them. You may already pay a monthly fee for an AI subscription that is barely used while your tests run. semula turns that subscription into an LLM API endpoint for your app: when a prompt arrives, your coding agent answers it over MCP or the CLI.

The rest is the cherry on top. Every answer is recorded, so the same prompt replays in milliseconds with no agent in the loop. semula normalises noise such as timestamps and reordered tool lists, matches tolerantly, and never serves a weak guess silently: near misses go to a review queue for you. Hand-written mocks break the moment a framework changes a prompt; recordings do not.

Related MCP server: EvalView

Quick start

You need Docker. Start semula in record mode:

docker run -d --name semula -p 127.0.0.1:8080:8080 \
  -e SEMULA_MODE=record -v semula-data:/data ghcr.io/leejianrong/semula

Point any OpenAI-compatible client at http://127.0.0.1:8080/v1. The first call for a new prompt is held:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Name a fruit."}]}'

In a second terminal, answer it as your coding agent would:

docker exec semula semula pending
docker exec semula semula answer <id> --text "Mango"

The held call returns Mango. Ask again and the stored answer comes back in a few milliseconds, even with a different model name or a new timestamp in the prompt. Open http://127.0.0.1:8080/ui/ to watch the calls, and answer parked ones from the Pending screen.

Switch a project to replay and it works offline; a prompt nobody recorded fails with 424 instead of inventing an answer:

docker exec semula semula mode replay --project default

Let your coding agent answer

semula speaks MCP over HTTP at /mcp/, so there is nothing to install:

claude mcp add --transport http semula http://127.0.0.1:8080/mcp/      # Claude Code
codex mcp add semula --url http://127.0.0.1:8080/mcp/                  # Codex

The agent calls wait_for_pending, reads the request, and calls answer_pending. Tell it to do that in a loop and your app's calls are answered as they arrive. The agent playbook covers answer formats, tool calls and errors, and docs/agents/claude-code-skill/ is a ready-made Claude Code skill. Both agents were run against the container to check this.

No MCP? The agent can use the CLI the same way you did: docker exec semula semula pending --wait 60 --json.

The CLI without Docker

Each release has the CLI as a single file for Linux and macOS (amd64 and arm64), with checksums. It talks to a running server:

chmod +x semula-*-linux-amd64 && mv semula-*-linux-amd64 ~/.local/bin/semula
semula --url http://127.0.0.1:8080 pending

What you get

  • The OpenAI Chat Completions API: text, streaming and tool calls. The OpenAI SDK and LangChain pass the conformance suite.

  • Record mode that parks unknown prompts, and replay mode that fails fast. Mode is set per project and kept across restarts.

  • Tiered matching: exact, normalised (timestamps, ids and paths ignored), approved aliases, word overlap, and optional meaning-based matching. Near misses wait in a review queue; a weak guess is never served by default.

  • Projects, entries with several answers, templates ({{now}}, {{uuid}}), versions with conflict detection, and pins that keep an agent from overwriting a human fix.

  • Redaction of secrets in what is stored; export and import as JSON files you can commit and diff.

  • A call log with a live tail, per-minute stats and a dashboard. SQLite by default, Postgres when you share it. Replay p95 is under 15 ms.

Documentation

Full docs, with a tutorial: https://leejianrong.github.io/semula/

Tutorial

Nine short pages, from the first recording to the dashboard

Install

Docker, the CLI binary, the Python package

Run it as a service

One always-on semula for every project on your machine

Self-host it

Docker Compose with HTTPS and an API key, or a Helm chart

Upgrade and back up

What is stored, upgrading, backing up

Reference

CLI, MCP tools, REST, settings, errors

docs/adr/

Why it is built the way it is

Contributing

From a clone (needs uv):

git clone https://github.com/leejianrong/semula && cd semula
uv sync --extra dev && make hooks
SEMULA_MODE=record uv run semula serve      # or: make run, make demo
make check                                  # lint, types, fast tests

See CONTRIBUTING.md. Agents: read AGENTS.md.

License

Apache License 2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).
      1
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      MCP server that lets coding agents test AI agents. Create YAML test cases, snapshot golden baselines, check for regressions, and generate visual reports all from inside Claude Code or any MCP-compatible tool. Works with LangGraph, CrewAI, OpenAI, Claude, Mistral, and any HTTP API.
      10
      1,798 PyPI
      142
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Local MCP server that lets your AI coding agent query its own cross-tool project history - file/command freshness, past test failures, cost & token spend, cache status, and session handoff - over stdio, 100% local, no telemetry.
      63
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      VCR for MCP servers: a zero-dependency stdio proxy that records and replays MCP JSON-RPC tool calls to local cassette files, enabling deterministic, offline testing of AI agent workflows without side-effects or rate limits.
      1
      MIT