agents-council-mcp 0.0.0

package/README.md

@@ -0,0 +1,226 @@
+<p align="center">
+  <img src="./.github/agents-council.jpg" alt="Agents Council" width="1280" height="714" />
+</p>
+
+<h2 align="center">Agents Council MCP: A lightweight MCP server for shared agent feedback sessions</h2>
+
+<p align="center">
+Status: <code>Experimental</code>
+</p>
+
+---
+
+## Overview
+
+Inspired by Andrej Karpathy's [LLM Council](https://github.com/karpathy/llm-council), **Agents Council** provides an MCP-based
+CLI tool that lets multiple agents communicate with each other and find solutions to your most complex tasks.
+
+## Features
+
+- Agent-to-Agent communication via MCP stdio server
+- Agents can join the council, submit questions and continue with their own sessions after they collected enough feedback
+- Markdown or JSON text output for agent readability or automation
+- Local, private state stored on disk. Can run fully offline when using local models.
+
+---
+
+## Installation
+
+Requires Node.js or Bun  
+<em>For Bun, use `bunx` instead of `npx`</em>
+
+<details>
+  <summary>amp</summary>
+    Use the amp CLI to add the Agents Council MCP server (<a href="https://ampcode.com/manual#mcp">guide</a>):
+
+```bash
+amp mcp add council npx agents-council-mcp@latest mcp
+```
+
+</details>
+
+<details>
+  <summary>Claude Code</summary>
+    Use the Claude Code CLI to add the Agents Council MCP server (<a href="https://docs.anthropic.com/en/docs/claude-code/mcp">guide</a>):
+
+```bash
+claude mcp add council npx agents-council-mcp@latest mcp
+```
+
+or use a predefined Agent Name and enable it for all projects with user scope
+
+```bash
+claude mcp add council -s user -- npx agents-council-mcp@latest mcp -n Opus
+```
+
+</details>
+
+<details>
+  <summary>Codex</summary>
+    Use the Codex CLI to add the Agents Council MCP server (<a href="https://developers.openai.com/codex/mcp/#add-a-mcp-server">guide</a>):
+
+```bash
+codex mcp add council npx agents-council-mcp@latest mcp
+```
+
+or with a custom Agent Name
+
+```bash
+codex mcp add council -- npx agents-council-mcp@latest mcp -n "Codex-5.2"
+```
+</details>
+
+<details>
+  <summary>Copilot CLI</summary>
+
+Start Copilot CLI:
+
+```
+copilot
+```
+
+Start the dialog to add a new MCP server by running:
+
+```
+/mcp add
+```
+
+Configure the following fields and press `CTRL+S` to save the configuration:
+
+- **Server name:** `council`
+- **Server Type:** `[1] Local`
+- **Command:** `npx agents-council-mcp@latest mcp`
+
+</details>
+
+<details>
+  <summary>Gemini CLI</summary>
+    Use the Gemini CLI to add the Agents Council MCP server (<a href="https://geminicli.com/docs/tools/mcp-server/#adding-a-server-gemini-mcp-add">guide</a>):
+
+```bash
+gemini mcp add council npx agents-council-mcp@latest mcp
+```
+
+or use a predefined Agent Name and enable it for all projects with user scope
+
+```bash
+gemini mcp add council -s user -- npx agents-council-mcp@latest mcp -n "Gemini 3 Pro"
+```
+
+</details>
+
+<details>
+  <summary>Other MCP integrations</summary>
+
+```json
+{
+  "mcpServers": {
+    "council": {
+      "command": "npx",
+      "args": [
+        "agents-council-mcp@latest",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+or use a predefined Agent Name
+
+```json
+{
+  "mcpServers": {
+    "council": {
+      "command": "npx",
+      "args": [
+        "agents-council-mcp@latest",
+        "mcp",
+        "-n",
+        "YourAgentName"
+      ]
+    }
+  }
+}
+```
+
+</details>
+
+## Quick start
+
+```text
+1. Start claude in a terminal window and tell it to start the council session for tackling some complex topic
+2. Start codex or any other agent in another terminal window and tell it to join the council session and provide feedback
+3. Let claude know that the feedback is ready and can check if this resolves the problem
+```
+
+## What problem does this tool solve?
+
+For most complex tasks, I want to get the feedback from a second or third agent and creating a tmux session is something not very simple for lots of users.
+I wanted to create the simplest possible tool that doesn't require any technical knowledge to run
+
+## MCP Tools
+
+Agents (or your MCP client) can use the following tools:
+
+- `start_council` to open a session with a request
+- `join_council` for first-time participants to fetch the request and responses
+- `get_current_session_data` to poll for new responses (optionally with a cursor)
+- `send_response` to reply
+- `close_council` to end the session with a conclusion
+
+## Agent Name behavior
+
+- Without `--agent-name`/`-n`, `start_council` and `join_council` require the `agent_name` field.
+- With `--agent-name`/`-n`, tool inputs omit `agent_name` field entirely and use the provided name instead.
+- The server may append `#1`, `#2`, etc. if a name is already used.
+
+## Response format (Experimental)
+
+You can choose to receive JSON or Markdown responses from the Agents Council MCP server.
+Some agents might work better with JSON and other with Markdown.
+
+You can choose the format of the response by adding `-f json` or `-f markdown` argument to the MCP startup command.
+
+```bash
+council mcp --format markdown
+council mcp --format json
+```
+
+## State
+
+State is stored at:
+
+```
+~/.agents-council/state.json
+```
+
+Override with the following env:
+
+```
+AGENTS_COUNCIL_STATE_PATH=/path/to/state.json
+```
+
+## Roadmap
+
+- [x] v0.1.0 - MCP Council
+- [ ] v0.2.0 - Chat UI
+- [ ] v0.3.0 - Spawn Claude automatically
+- [ ] v0.4.0 - Spawn Codex automatically
+- [ ] v0.5.0 - Spawn Gemini automatically
+- [ ] v0.6.0 - Multiple council sessions in parallel
+- [ ] v0.7.0 - Connect to external LLMs via API Keys
+- [ ] v Next - Submit your idea
+
+## Development
+
+See `DEVELOPMENT.md` for local setup and workflow details.
+
+## Compatibility
+
+This project is highly experimental and does not maintain backwards compatibility. Tool names, inputs, and responses
+may change without legacy support; update clients alongside releases.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "agents-council-mcp",
+  "version": "0.0.0",
+  "type": "module",
+  "files": [
+    "scripts/*.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "council": "scripts/cli.cjs"
+  },
+  "optionalDependencies": {
+    "agents-council-mcp-darwin-arm64": "*",
+    "agents-council-mcp-darwin-x64": "*",
+    "agents-council-mcp-linux-arm64": "*",
+    "agents-council-mcp-linux-x64": "*",
+    "agents-council-mcp-windows-x64": "*"
+  },
+  "scripts": {
+    "build": "bun build src/cli/index.ts --compile --outfile dist/council",
+    "cli": "bun src/cli/index.ts",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "format:check": "biome check --formatter-enabled=true --linter-enabled=false .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "package.json": [
+      "biome check --write --files-ignore-unknown=true"
+    ],
+    "*.json": [
+      "biome check --write --files-ignore-unknown=true"
+    ],
+    "src/**/*.{ts,js}": [
+      "biome check --write --files-ignore-unknown=true"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.25.1",
+    "zod": "4.2.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@types/bun": "1.3.5",
+    "husky": "9.1.7",
+    "lint-staged": "16.2.7",
+    "typescript": "5.9.3"
+  },
+  "author": "Alex Gavrilescu (https://github.com/MrLesk)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrLesk/agents-council.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MrLesk/agents-council/issues"
+  },
+  "homepage": "https://github.com/MrLesk/agents-council",
+  "keywords": [
+    "mcp",
+    "council",
+    "agents",
+    "cli",
+    "mcp-server"
+  ],
+  "license": "MIT"
+}

package/scripts/cli.cjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const { resolveBinaryPath } = require("./resolveBinary.cjs");
+
+let binaryPath;
+try {
+  binaryPath = resolveBinaryPath();
+} catch {
+  console.error(`Binary package not installed for ${process.platform}-${process.arch}.`);
+  process.exit(1);
+}
+
+const rawArgs = process.argv.slice(2);
+const cleanedArgs = rawArgs.filter((arg) => {
+  if (arg === binaryPath) return false;
+  try {
+    const pattern = /node_modules[/\\]agents-council-mcp-(darwin|linux|windows)-[^/\\]+[/\\]council(\.exe)?$/i;
+    return !pattern.test(arg);
+  } catch {
+    return true;
+  }
+});
+
+const child = spawn(binaryPath, cleanedArgs, {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+child.on("exit", (code) => {
+  process.exit(code || 0);
+});
+
+child.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    console.error(`Binary not found: ${binaryPath}`);
+    console.error(`Please ensure you have the correct version for your platform (${process.platform}-${process.arch})`);
+  } else {
+    console.error("Failed to start council:", err);
+  }
+  process.exit(1);
+});

package/scripts/postuninstall.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+
+const platformPackages = [
+  "agents-council-mcp-linux-x64",
+  "agents-council-mcp-linux-arm64",
+  "agents-council-mcp-darwin-x64",
+  "agents-council-mcp-darwin-arm64",
+  "agents-council-mcp-windows-x64",
+];
+
+const packageManager = process.env.npm_config_user_agent?.split("/")[0] || "npm";
+
+console.log("Cleaning up platform-specific packages...");
+
+for (const pkg of platformPackages) {
+  const args = packageManager === "bun" ? ["remove", "-g", pkg] : ["uninstall", "-g", pkg];
+
+  const child = spawn(packageManager, args, {
+    stdio: "pipe",
+    windowsHide: true,
+  });
+
+  child.on("exit", (code) => {
+    if (code === 0) {
+      console.log(`Cleaned up ${pkg}`);
+    }
+  });
+}
+
+console.log("Platform package cleanup completed.");

package/scripts/resolveBinary.cjs

@@ -0,0 +1,33 @@
+function mapPlatform(platform = process.platform) {
+  switch (platform) {
+    case "win32":
+      return "windows";
+    case "darwin":
+    case "linux":
+      return platform;
+    default:
+      return platform;
+  }
+}
+
+function mapArch(arch = process.arch) {
+  switch (arch) {
+    case "x64":
+    case "arm64":
+      return arch;
+    default:
+      return arch;
+  }
+}
+
+function getPackageName(platform = process.platform, arch = process.arch) {
+  return `agents-council-mcp-${mapPlatform(platform)}-${mapArch(arch)}`;
+}
+
+function resolveBinaryPath(platform = process.platform, arch = process.arch) {
+  const packageName = getPackageName(platform, arch);
+  const binary = `council${platform === "win32" ? ".exe" : ""}`;
+  return require.resolve(`${packageName}/${binary}`);
+}
+
+module.exports = { getPackageName, resolveBinaryPath };