{"id":"98358bd1-abba-4d3d-b902-7fb5dd8dd9c9","slug":"imladris","kind":"mcp","name":"imladris","summary":"Rivendell-style council for AI agents: a stdio MCP server that convenes multi-provider model panels and returns grounded analysis.","owner":"FeanorsCodeSL","repoUrl":"https://github.com/FeanorsCodeSL/imladris","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-23T14:38:58.000Z","addedAt":"2026-10-21T17:36:02.406Z","logoUrl":"https://avatars.githubusercontent.com/u/235730147?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T01:23:18.108Z","sample":false,"url":"https://conduits.dev/tools/imladris","language":"Python","transports":["stdio"],"install":{"pypi":"imladris"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Imladris\n\nNamed for Imladris (Rivendell), seat of the Council of Elrond — where\nrepresentatives of every free people gathered to weigh a hard decision together.\n\n![Imladris Council](docs/images/Imladris%20Council.gif)\n\n## Design (source of truth)\n\n[`docs/architecture/`](docs/architecture/) — overview, pipeline, MCP surface,\nconfiguration reference, provider abstraction, judge, security, and deployment.\n\n## How it works (one paragraph)\n\nThe harness's native model calls the `imladris` MCP tool (via the `/council`\nor `/council-session` prompt). The server fans the prompt out to the configured panel (1–8\nmembers) **concurrently** (each provider is a plain HTTPS call), collects answers\n(with partial-result tolerance), then runs an **API-side analysis judge**\n(consensus / contradictions / partial coverage / unique insights / blind spots).\nThe tool returns that analysis plus all raw panel answers. The native model reads\nboth and **authors the final answer**. A session call uses a local\n`~/.imladris/sessions/<thread_id>.json` store to rebuild prior user/assistant turns for\nthe next panel pass. An MCP server can't call back into the\nharness model, so the judge is API-side and the native model is always the outer\nauthor.\n\n## Install\n\nBootstrap [`uv`](https://docs.astral.sh/uv/) and install the `imladris` console\ntool with a single command. You do not need a local checkout of this repository:\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/FeanorsCodeSL/imladris/main/scripts/install.sh | sh\n```\n\n```powershell\n# Windows\nirm https://raw.githubusercontent.com/FeanorsCodeSL/imladris/main/scripts/install.ps1 | iex\n```\n\nEach script installs `uv` if absent, resolves or installs Python 3.13, removes any\nprevious `imladris` uv tool environment, reinstalls with the resolved Python\ninterpreter, and verifies `imladris --help` before finishing. This puts two\ncommands on your console PATH: `imladris` (the configurator TUI) and\n`imladris-mcp` (the MCP stdio server harnesses spawn).\nUntil a PyPI release is uploaded, this git-URL install requires `git` on PATH;\nthe installer checks that up front.\n\nUse the installer as the supported install workflow, including for local source\ntesting. Raw `uv tool install .` is only useful when deliberately debugging uv\nitself because it bypasses the installer safeguards.\n\nThen run the configurator:\n\n```bash\nimladris\n```\n\n![Imladris TUI dashboard](docs/images/tui-dashboard.svg)\n\nThe full-screen configurator loads the current config, shows the council roster,\nlets you add/edit/delete members, assign the **judge** role, writes\n`~/.imladris/config.json` + `~/.imladris/.env` (0600), and wires selected\nharnesses (Claude Code / Codex / OpenCode) with the `imladris` MCP entry. After\nthat, continue in your harness and invoke `/council`, `/council-session`, or the\n`imladris` tool when you want deliberation.\n\nRun `imladris doctor` to print the resolved roster, roles, and wired harnesses\n(no secrets). Use `imladris refresh-catalog` or the TUI refresh action to update\nthe local models.dev cache; runtime deliberation only reads cache/seed data.\nCouncil sessions are local files under `~/.imladris/sessions/`. Clear one or all\nof them with `imladris clear-sessions [thread_id]` or the `imladris_clear_sessions`\nMCP tool.\n\n## Repository layout\n\n```\norchestrator/        the service package\n  mcp_server.py      FastMCP server — tools: imladris, imladris_status, imladris_clear_sessions; council + council-session prompts; main()\n  panel.py           panel fan-out orchestration (partial results + degradation)\n  judge.py           API-side analysis judge\n  model_catalog.py   offline-first model metadata, models.dev parser, cache helpers\n  budget.py          advisory context-budget estimates\n  sessions.py        local council-session store and message reconstruction\n  providers/         single OpenAI-compatible chat provider kind + factory\n  settings.py        JSON/YAML + env config loading/validation; roles panel/judge\n  models.py          Pydantic request/response models\n  interfaces.py      Protocol seams; fakes.py — deterministic test doubles\n  costing.py         cost estimation; json_utils.py — tolerant judge JSON\n  cli/               imladris configurator: TUI, catalog, config ops, secrets, probe, harness/\n  tests/             pytest suite (respx for HTTP)\nconfig/              imladris.example.yaml (illustrative providers, presets, pricing)\nscripts/             install.sh, install.ps1, stdio smoke (Bash + PowerShell)\ndocs/architecture/   live architecture, configuration, security, deployment references\n.github/workflows/   CI, sonar\n.agents/skills/      imladris-deliberate skill\n```\n\n## Develop\n\nRequires **Python 3.13**.\n\n```bash\npython -m venv .venv\n./.venv/bin/python -m pip install -r orchestrator/requirements-dev.txt\n\n./.venv/bin/ruff check orchestrator           # lint\n./.venv/bin/ruff format --check orchestrator  # style gate (CI enforces)\n./.venv/bin/python -m pytest                  # tests\n\n./.venv/bin/python -m orchestrator.mcp_server # run the MCP server over stdio\nIMLADRIS_SOURCE=\"$(pwd)\" ./scripts/install.sh # install/test from this checkout\n```\n\nOn Windows, use the same installer path:\n\n```powershell\n.\\scripts\\install.ps1 -Source .\n```\n\n## Configuration\n\nRun `imladris` to write `~/.imladris/config.json` and `~/.imladris/.env` (0600).\nThe in-repo `config/imladris.example.yaml` is illustrative only. Both JSON and\nYAML config files are supported by extension; the TUI writes JSON.\n**Secrets live only in env vars referenced by name** (`api_key_env`) from the\nconfig — never in the config file, never logged, never returned by\n`imladris_status`.\n\nResolution: `--config <path>` → `IMLADRIS_CONFIG` → `./imladris.{json,yaml}` →\n`~/.imladris/config.{json,yaml}`.\n\n## Integration\n\nPer-harness setup (Claude Code, Codex, OpenCode) is wired automatically by the\n`imladris` configurator. Every entry launches `imladris-mcp` over stdio with\n`IMLADRIS_CONFIG` pointed at `~/.imladris/config.json`. For the manual config\nsnippets, see [`docs/architecture/06-deployment.md`](docs/architecture/06-deployment.md).\n\n## License\n\n[MIT](LICENSE). See also `SECURITY.md`, `CONTRIBUTING.md`, `THIRD-PARTY-NOTICES.md`.\n"}