If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BeehiveInnovations/pal-mcp-server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 6 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BeehiveInnovations/pal-mcp-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BeehiveInnovations/pal-mcp-server.

What it runs against: a local clone of BeehiveInnovations/pal-mcp-server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BeehiveInnovations/pal-mcp-server | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 173 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BeehiveInnovations/pal-mcp-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BeehiveInnovations/pal-mcp-server.git
#   cd pal-mcp-server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BeehiveInnovations/pal-mcp-server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BeehiveInnovations/pal-mcp-server(\\.git)?\\b" \\
  && ok "origin remote is BeehiveInnovations/pal-mcp-server" \\
  || miss "origin remote is not BeehiveInnovations/pal-mcp-server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "clink/agents/base.py" \\
  && ok "clink/agents/base.py" \\
  || miss "missing critical file: clink/agents/base.py"
test -f "clink/registry.py" \\
  && ok "clink/registry.py" \\
  || miss "missing critical file: clink/registry.py"
test -f "config.py" \\
  && ok "config.py" \\
  || miss "missing critical file: config.py"
test -f "clink/models.py" \\
  && ok "clink/models.py" \\
  || miss "missing critical file: clink/models.py"
test -f "clink/parsers/base.py" \\
  && ok "clink/parsers/base.py" \\
  || miss "missing critical file: clink/parsers/base.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 173 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~143d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BeehiveInnovations/pal-mcp-server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PAL MCP is a Model Context Protocol server that abstracts multiple AI model providers (Claude, Gemini, OpenAI, Grok, Azure, Ollama, OpenRouter) into unified interfaces, enabling Claude Code, Gemini CLI, Codex CLI, and other AI development tools to access and orchestrate different LLMs from a single context. Its core capability is the clink tool, which spawns isolated CLI subagents (e.g., Codex spawning a specialized code-reviewer agent) with full context preservation across tool handoffs, solving the problem of context pollution and enabling consensus-driven AI workflows. Modular Python package: clink/agents/ contains provider-specific agent implementations (base.py, claude.py, gemini.py, codex.py), clink/parsers/ mirrors agent structure for response parsing, clink/registry.py manages provider registration, conf/ holds provider configs (cli_clients/ for Claude/Gemini/Codex JSONs, azure_models.json), and workflows are defined in .claude/commands/ for Claude Code integration. Entry point is clink/__init__.py with CLI client configs in conf/cli_clients/.

AI-powered developers and DevOps engineers who work with Claude Code, Gemini CLI, Codex CLI, or Cursor and want to leverage multiple LLM providers simultaneously, run isolated specialized agents (code reviewers, planners, security auditors) without polluting their main context window, and orchestrate multi-model consensus before implementation.

Actively developed with semantic versioning CI/CD (GitHub Actions workflows for testing and Docker releases visible), but appears pre-1.0 given the recent rebranding from 'Zen MCP' to 'PAL MCP'. The codebase is substantial (~3M lines of Python) with structured agent/parser architecture, indicating serious engineering effort, though test coverage and issue backlog maturity are unclear from the file list alone.

Medium risk: depends on rapid-moving APIs (google-genai, openai, mcp>=1.0.0) with strict version constraints (httpx 0.28.0 compatibility noted), and the core orchestration logic touches multiple LLM provider integrations that could break with API changes. Single Python maintainer risk is possible given the concentrated ownership. The experimental clink CLI-spawning feature is powerful but adds complexity and subprocess management risk.

Recent work includes the new clink CLI-to-CLI bridge feature for spawning subagents, Docker release automation via docker-release.yml, semantic versioning PR validation (semantic-pr.yml), and a code quality check matrix (bash/PowerShell scripts). The .claude/commands/fix-github-issue.md suggests active integration with Claude Code workflows.

git clone https://github.com/BeehiveInnovations/pal-mcp-server.git
cd pal-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys (ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY, etc.)
python -m clink  # or invoke via Claude Code / Gemini CLI

Daily commands: For MCP server mode: python -m clink serve (inferred from MCP pattern). For direct CLI: python -m clink <provider> <prompt> or via clink with <provider> <role> to <task> when integrated into Claude Code/Gemini CLI. Docker: docker build -t pal-mcp . && docker run -e OPENAI_API_KEY=$OPENAI_API_KEY pal-mcp.

• clink/agents/base.py — Base agent abstraction that all provider-specific agents (Claude, Gemini, Codex) inherit from—core to the multi-model dispatch system.
• clink/registry.py — Central registry managing agent and parser instantiation across multiple AI providers; critical for plugin/provider routing logic.
• config.py — Main configuration loader handling environment variables, provider credentials, and model selection—load-bearing for all provider initialization.
• clink/models.py — Pydantic data models defining agent responses, tool parameters, and provider-agnostic message schemas across all integrations.
• clink/parsers/base.py — Base parser abstraction for extracting structured data from each provider's response format (Claude, Gemini, Codex); essential for output normalization.
• conf/openai_models.json — Provider model configuration registry—defines available models, capabilities, and cost; referenced by agent routing logic.
• README.md — High-level overview of PAL's multi-provider abstraction and CLI-to-CLI bridge (clink tool); orients new contributors to the project's mission.

Add a new AI provider (e.g., Anthropic, OpenRouter, Ollama)

1. Create provider agent class inheriting from base.Agent in clink/agents/ (clink/agents/yourprovider.py)
2. Implement send_message() to translate unified message format to provider's API (clink/agents/yourprovider.py)
3. Create corresponding parser in clink/parsers/ to normalize provider responses (clink/parsers/yourprovider.py)
4. Register agent and parser in clink/registry.py's get_agent() and get_parser() factory methods (clink/registry.py)
5. Add provider credentials to .env.example and config.py loader (config.py)
6. Create model registry JSON (e.g., conf/yourprovider_models.json) listing available models (conf/yourprovider_models.json)
7. Document setup instructions in docs/yourprovider-setup.md (docs/yourprovider-setup.md)

Add a new MCP tool for agents to use

1. Define tool schema (name, parameters, description) in clink/constants.py or a new tools module (clink/constants.py)
2. Implement tool handler function with same signature across all agent types (clink/agents/base.py)
3. Register tool in agent registry and ensure all provider parsers handle tool calls for this tool (clink/registry.py)
4. Add documentation including examples and expected outputs (docs/tools/yourtool.md)

Add support for a new external CLI (for clink bridge)

1. Create CLI client spec JSON with endpoint, auth method, and command format (conf/cli_clients/yourcli.json)
2. Add CLI client configuration loader in config.py (config.py)
3. Implement CLI agent wrapper that spawns subprocess and parses stdout (clink/agents/clink.py)
4. Document CLI bridge setup and compatibility in docs/tools/clink.md (docs/tools/clink.md)

Configure custom model with custom endpoint

1. Add model definition to conf/custom_models.json with endpoint URL and auth header (conf/custom_models.json)
2. Update config.py to load custom model settings and merge with provider list (config.py)
3. If new provider type, implement corresponding agent in clink/agents/ (clink/agents/base.py)
4. Test model selection via clink/registry.py get_agent() method (clink/registry.py)

• Pydantic v2 — Type-safe data validation and serialization across all provider request/response formats; enables runtime schema enforcement.
• MCP (Model Context Protocol) — Standard for multi-model orchestration; decouples tool definitions from provider implementations.
• Python async/await — Enables concurrent provider requests and tool execution; supports streaming responses from multiple LLMs simultaneously.
• JSON config files (provider models) — Zero-code model registry updates; allows users to add/customize models without code changes.
• Docker + docker-compose — Reproducible deployment across local dev and production; pre-loads all provider credentials.

• Abstract providers via agents + parsers instead of unified SDK wrapper

  • Why: Each provider has drastically different APIs, authentication, and response schemas (tool_use vs function_calling vs raw text).
  • Consequence: More code per provider but cleaner separation of concerns; easier to add providers incrementally without breaking existing ones.

• undefined

  • Why: undefined
  • Consequence: undefined

Environment variables: Must set API keys for each provider individually (ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_KEY, etc.); missing keys silently disable providers rather than loudly failing. Config file paths: conf/ JSON files use relative paths; running from wrong directory breaks provider discovery. Async runtime: Code uses asyncio heavily; don't call agent methods from sync contexts without asyncio.run(). CLI version lock: openai>=1.55.2 is pinned for httpx 0.28.0 compatibility; upgrading may break underlying transports. Subprocess spawning in clink: Forking CLIs inherits parent env but not all context state; clink subagent handoff may lose streaming or real-time features. MCP protocol version: Tied to mcp>=1.0.0; older Claude Code / Gemini CLI versions may not support this server's interface.

• Model Context Protocol (MCP) — PAL MCP is an MCP server; understanding MCP's request/response model, tool registration, and resource lifecycle is fundamental to extending this codebase
• Provider Abstraction Pattern — PAL's core architecture abstracts provider-specific APIs (Claude, Gemini, OpenAI) behind unified Agent and Parser interfaces; mastering this pattern is essential for adding new LLM providers
• Async/await and asyncio — The entire codebase uses async def and asyncio for concurrent LLM requests; Python async is non-negotiable to modify agents or add streaming features
• CLI Subagent Spawning & Context Isolation — The new clink feature spawns isolated subprocess CLI instances with context inheritance; understanding subprocess lifecycle, environment passing, and context serialization is critical for clink debugging
• Pydantic Data Validation — All configuration and API responses are validated via Pydantic 2.0+; understanding schema definition and validation errors is essential for adding new config options or API wrappers
• Registry Pattern for Plugin Discovery — PAL uses registry.py to dynamically discover and instantiate providers; this pattern enables extensibility without modifying core code
• Response Parsing & Normalization — Different LLM APIs return fundamentally different response formats (streaming vs. batch, token counts, tool calls); the parser layer normalizes these into a common interface that clink can hand off between tools

• anthropics/anthropic-sdk-python — Official Python SDK for Claude that PAL MCP wraps; understanding this is essential for the Claude agent implementation
• google/generative-ai-python — Official Google Gemini SDK that PAL MCP abstracts; needed for Gemini agent provider implementation
• openai/openai-python — Official OpenAI SDK for GPT models and Codex; directly used by the OpenAI/Codex agents in this repo
• modelcontextprotocol/python-sdk — The MCP protocol SDK that PAL MCP is built on; defines the server interface that Claude Code and Gemini CLI communicate with
• google-gemini/gemini-cli — External CLI that clink bridges into; understanding its subcommand interface is needed to implement clink subagent spawning

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for agent implementations (claude.py, gemini.py, codex.py)

The repo has development dependencies for pytest and pytest-asyncio listed in requirements, but no visible test files in the partial file structure. The agents module (clink/agents/) has base.py, claude.py, gemini.py, and codex.py implementations that handle different AI provider integrations. These agent classes need unit tests to verify correct API calls, response parsing, error handling, and model registry interactions. This is critical for a multi-provider abstraction layer where bugs in agent logic affect all downstream consumers.

• [ ] Create tests/agents/ directory structure
• [ ] Write tests for clink/agents/claude.py covering initialization, request formatting, and response parsing
• [ ] Write tests for clink/agents/gemini.py with similar coverage
• [ ] Write tests for clink/agents/codex.py with similar coverage
• [ ] Write tests for clink/agents/base.py abstract base class contract
• [ ] Add async test fixtures for mocking external API calls using pytest-mock
• [ ] Ensure tests verify registry.py integration for model resolution
• [ ] Add test coverage reporting to .coveragerc

Add parser unit tests and integration tests for all supported CLI formats (claude.py, gemini.py, codex.py)

The repo has parser implementations in clink/parsers/ for Claude, Gemini, and Codex CLIs, which extract structured data from different CLI output formats. Since this is a multi-provider abstraction layer and the new clink tool bridges CLI-to-CLI communication, parser correctness is critical. Missing tests means regressions in parsing could silently break the abstraction. Tests should validate that each parser correctly handles tool definitions, arguments, and responses from their respective CLI formats.

• [ ] Create tests/parsers/ directory
• [ ] Write tests for clink/parsers/claude.py with sample Claude CLI output fixtures
• [ ] Write tests for clink/parsers/gemini.py with sample Gemini CLI output fixtures
• [ ] Write tests for clink/parsers/codex.py with sample Codex CLI output fixtures
• [ ] Write tests for clink/parsers/base.py parser contract
• [ ] Add edge case tests for malformed CLI outputs and error scenarios
• [ ] Add integration tests validating parser output can be consumed by agents module

Create GitHub Actions workflow to validate model configuration files against schema

The repo maintains multiple model configuration JSON files (conf/azure_models.json, conf/gemini_models.json, conf/openai_models.json, conf/openrouter_models.json, conf/dial_models.json, conf/custom_models.json, conf/xai_models.json, and conf/cli_clients/*.json). Without schema validation in CI, contributors could add malformed model configs that break at runtime. This is especially important since models.py likely depends on these configs. A new GitHub Action should validate all config files against a JSON schema on PRs, preventing configuration errors from reaching main.

• [ ] Create a JSON schema file (conf/models-schema.json) defining required fields for model entries
• [ ] Create .github/workflows/validate-config.yml that runs on PR
• [ ] Use a JSON schema validator action (e.g., ajv-cli or custom Python script in code_quality_checks.sh)
• [ ] Validate all conf/*.json files match the schema
• [ ] Add validation for conf/cli_clients/*.json with appropriate schema constraints
• [ ] Document schema in docs/adding_providers.md or new docs/model-configuration.md
• [ ] Add pre-commit hook to code_quality_checks.sh for local validation

• Add unit tests for clink/parsers/codex.py — the Codex response parser currently has no test coverage visible; write tests that validate parsing of code blocks, error messages, and streaming responses against fixture CodexCLI outputs
• Document the provider configuration schema — create docs/provider-config.md explaining the JSON structure in conf/cli_clients/ and conf/azure_models.json with examples for adding custom OpenRouter or Ollama endpoints
• Implement provider health-check command — add a clink health subcommand that validates all configured API keys, tests connectivity to each provider's endpoint, and reports which providers are ready; helps onboarding and debugging

• High · API Keys in Environment Configuration — .env.example, .gitignore. The .env.example file contains placeholder API keys for multiple providers (GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI). While these are examples, there is significant risk that developers will commit actual API keys to version control. The repository structure shows multiple API key configurations without evidence of strict .gitignore enforcement for .env files. Fix: Ensure .env files (not .env.example) are strictly listed in .gitignore. Implement pre-commit hooks to prevent credential commits. Consider using git-secrets or similar tools. Document API key management best practices prominently in README.md and CONTRIBUTING.md.
• High · Unvalidated Third-Party API Key Handling — clink/agents/base.py, clink/agents/claude.py, clink/agents/gemini.py, config.py. The application accepts API keys for multiple external providers (OpenAI, Google Gemini, Azure, XAI, Ollama) without visible input validation or sanitization. Keys are passed directly to external providers without apparent verification of format or safe handling. Fix: Implement API key validation (format checks, length validation). Use secure credential storage (environment variables only, never in code). Add input sanitization before passing to external APIs. Implement key rotation policies and expiration monitoring.
• High · Unsafe Docker Multi-Stage Build Configuration — Dockerfile. The Dockerfile uses Python 3.11-slim with pip installing packages without hash verification or lock file enforcement. The build stage doesn't pin versions in requirements.txt, creating supply chain risks. Additionally, the second stage copies from builder without explicitly removing unnecessary build artifacts. Fix: Use requirements.txt with pinned versions and cryptographic hashes (pip freeze or poetry.lock). Implement multi-stage builds properly to minimize final image size. Add explicit cleanup of build artifacts. Use --no-cache-dir consistently. Consider using distroless base images. Scan images with Trivy or similar tools.
• High · No Input Validation on Model Configuration Files — conf/ directory, config.py. The application loads multiple JSON configuration files (conf/azure_models.json, conf/custom_models.json, conf/openrouter_models.json, etc.) without visible validation. These files control model selection and API behavior. Malicious or corrupted config files could lead to unintended API calls or prompt injection. Fix: Implement JSON schema validation for all configuration files. Use Pydantic models to validate loaded configs. Sign or verify integrity of config files. Restrict file read permissions. Implement configuration whitelisting for allowed models and providers.
• Medium · Dependency Version Constraints Too Loose — requirements.txt (implicit from Package file content). Dependencies use minimum version specifications (>=) without upper bounds. For example, 'openai>=1.55.2' could accept incompatible future versions. This creates supply chain risks from transitive dependencies and breaking changes. Fix: Use semantic versioning constraints (e.g., >=1.55.2,<2.0.0). Pin critical dependencies exactly. Use a lock file (poetry.lock or pip freeze). Implement dependency scanning with tools like Safety or Dependabot. Review dependencies quarterly.
• Medium · Incomplete Security Policy — SECURITY.md. SECURITY.md file is truncated/incomplete. The disclaimer section ends abruptly at 'Third-Party Services' without completing information about liability, responsible disclosure, or security contact procedures. Fix: Complete the security policy with: responsible disclosure process, security contact email, vulnerability reporting procedures, PGP key for sensitive reports, SLA for patches, and clear liability disclaimers.
• Medium · No Evidence of Secret Scanning in CI/CD — .github/workflows/test.yml, .github/workflows/semantic-pr.yml. While GitHub workflows are present (.github/workflows/), there is no visible evidence of secret scanning (git-secrets, detect-secrets, or GitHub secret scanning integration) in the CI/CD pipeline to prevent credential leaks. Fix: Add secret scanning to CI/CD pipelines. Implement git-secrets or similar in pre-commit hooks. Enable GitHub secret scanning in repository settings. Add secret rotation reminders in documentation.
• Medium · Insufficient CORS/Security Headers in Server Configuration — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.