hoopoe

AirspaceTechnologies/hoopoe

3.1

If you are the rightful owner of hoopoe and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Hoopoe is a customizable MCP proxy server designed to filter tools, preset parameters, and maintain session context, enabling the creation of specialized assistants and orchestration of multi-agent architectures.

Hoopoe

Tests License: MIT Python 3.10+

A customizable MCP proxy server that filters tools, presets parameters, and maintains session context. Define specialized assistants from generic servers (e.g., planning_assistant from Codex) and orchestrate multi-agent architectures with Claude Code.

Why Hoopoe

  • Claude Code as the orchestrator: use Claude Code to coordinate Codex sessions via Hoopoe’s MCP‑HTTP bridge; Gemini CLI coming soon.
  • Persist conversations: captures session IDs and maintains context over a single connection (fixes context amnesia).
  • Configure specialists: define role‑specific tools in src/config.yaml and call them deterministically.
  • Git‑aware workflows: built‑in tools to branch, commit, push, and open PRs (via gh).
  • Safe by design: explicit sandbox and approval policies; bound to a validated Git worktree.

See agent patterns this enables:

Quick Start

Prerequisites

  • Python 3.10+
  • uv package manager
  • Codex CLI installed and on PATH
  • Optional: Node (for MCP Inspector), GitHub CLI gh (for PR tools)

Install and run

git clone https://github.com/AirspaceTechnologies/hoopoe.git
cd hoopoe
uv sync

# Start the MCP HTTP server (port 8957)
uv run python -m src.mcp_server

Open in MCP Inspector (recommended for sessions)

# Encode your project path (must be a Git repo)
echo -n "/path/to/your/git/repo" | base64

npx @modelcontextprotocol/inspector \
  "http://localhost:8957/mcp?worktree=<base64_encoded_path>"

60‑Second Demo

In MCP Inspector Web UI (persistent connection):

  1. Call codex with a prompt like: “Create a Python function to compute Fibonacci numbers.”
  2. Note the session hint in the response (Hoopoe appends the session ID).
  3. Call codex-reply with a follow‑up prompt and that session ID — the conversation continues with full context.

Tip: Use the coding_assistant or code_reviewer tools from src/config.yaml for opinionated behaviors.

Session Strategy (New vs Reuse)

  • Start a new session: call codex or a role tool (e.g., planning_assistant) to create a clean thread. Use for planning, branching work, or different constraints (model, sandbox, cwd).
  • Reuse an existing session: call codex-reply with the sessionId returned earlier. Use for iterative refinement within the same context.
  • Parallelize: spawn multiple sessions (e.g., two planning attempts) and have Claude Code compare/merge results.

Problems This Solves

  • Context amnesia: session IDs are captured and surfaced to keep long‑running conversations coherent.
  • Brittle CLI flows: a stable HTTP endpoint makes Codex easy to call from orchestrators and workflows.
  • Unstructured multi‑agent setups: define specialists in YAML; Claude Code routes tasks deterministically.
  • Limited automation around repos: Git tools perform routine branch/PR flows without leaving the agent loop.
  • Debug opacity: optional Rust‑level Codex logs and explicit parameter capture improve observability.
  • Safety and reproducibility: per‑connection isolation, clear sandbox/approval policies, and validated worktrees.

Git Workflow Example (Optional)

Prerequisites: origin remote configured, gh auth login completed.

From MCP Inspector, call git_new_branch_pr with:

  • branch_name: feature/my-change
  • files: ["README.md"]
  • commit_message: chore: update docs
  • pr_title: Update docs
  • pr_description: One‑line summary

Hoopoe will create the branch, commit, push, and open a PR via gh.

Configure Tools

  • Edit src/config.yaml to define tools, defaults (model, sandbox, cwd), and which params are exposed.
  • Worktree is passed via URL: ?worktree=<base64_path_to_repo> (validated at tool execution time).
  • See docs for complete examples and parameter reference:
    • tests/fixtures/codex_tool_examples.yaml

Troubleshooting & Details

  • — more end‑to‑end examples
  • — tool reference, worktree validation, debug logging
  • — common errors and fixes
  • — how Hoopoe maps to supervisor/specialist patterns
  • — the pain points this solves
  • — architecture answers to those pains

Limitations

  • Sessions persist only for the lifetime of a single HTTP connection (Web UI works best).
  • CLI invocations create new connections (no session continuity across commands).
  • Single backend today: this server proxies to Codex MCP. Multi‑backend (Gemini CLI, additional Claude Code sessions) is on the roadmap; see docs/AGENT_PATTERNS.md for the support matrix and workarounds.
  • Some Codex parameters may vary by Codex version.

Contributing & License

Contributions welcome! See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

MIT License. See LICENSE.

—

About the name: the hoopoe is a legendary messenger bird — a fitting symbol for a protocol bridge.

Disclaimer: This is an unofficial, third-party project. Not affiliated with OpenAI, Anthropic, or Google. "Codex" and "OpenAI" are trademarks of OpenAI. "Claude Code" and "Anthropic" are trademarks of Anthropic. "Gemini" and "Google" are trademarks of Google LLC.