agenthive-mcp 1.0.0__py3-none-any.whl

agenthive_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""agenthive-mcp: MCP server exposing AgentHive's member-level API as tools."""
+
+__version__ = "0.1.0"

agenthive_mcp/client.py

@@ -0,0 +1,73 @@
+"""Lazy-initialised AgentHive HTTP client.
+
+Reads AGENTHIVE_URL/AGENTHIVE_TOKEN/AGENTHIVE_TEAM_ID from the environment
+at call time (not import time), so importing this module never fails just
+because env vars are unset - useful for tests, linting, and Docker image
+builds, same reasoning as snyk-mcp's client.py.
+
+Deliberately plain urllib rather than an SDK or httpx dependency: AgentHive
+is a small first-party HTTP API (see polarpoint-io/agenthive's server.py),
+not a large third-party surface worth a client library, and this repo's
+whole point is staying a thin, dependency-light bridge (see ADR.md's "Why
+not build an LLM-request proxy" in the main agenthive repo).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class AgentHiveConfigError(RuntimeError):
+    """Raised when required AGENTHIVE_* env vars are missing."""
+
+
+class AgentHiveError(RuntimeError):
+    """Raised on any non-2xx response from the AgentHive API, with the
+    server's own error message rather than a generic HTTP status."""
+
+
+def get_config() -> tuple[str, str, str]:
+    """Return (base_url, token, team_id) from the environment, or raise
+    AgentHiveConfigError naming exactly what's missing."""
+    missing = [
+        name for name in ("AGENTHIVE_URL", "AGENTHIVE_TOKEN", "AGENTHIVE_TEAM_ID")
+        if not os.environ.get(name)
+    ]
+    if missing:
+        raise AgentHiveConfigError(
+            "agenthive-mcp is missing " + ", ".join(missing) + " - set these in "
+            "the MCP client config's env block (see README.md)."
+        )
+    return (
+        os.environ["AGENTHIVE_URL"].rstrip("/"),
+        os.environ["AGENTHIVE_TOKEN"],
+        os.environ["AGENTHIVE_TEAM_ID"],
+    )
+
+
+def request(method: str, path: str, body: dict | None = None, query: dict | None = None) -> dict:
+    """A single AgentHive API call using the caller's personal token.
+    Every MCP tool in server.py is a thin pass-through to this."""
+    base_url, token, _ = get_config()
+    url = base_url + path
+    if query:
+        url += "?" + urllib.parse.urlencode(query)
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("X-API-Key", token)
+    req.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        try:
+            detail = json.loads(e.read()).get("error", "unknown error")
+        except (json.JSONDecodeError, AttributeError):
+            detail = e.reason
+        raise AgentHiveError(f"{e.code}: {detail}") from None
+    except urllib.error.URLError as e:
+        raise AgentHiveError(f"could not reach {base_url}: {e.reason}") from None

agenthive_mcp/server.py

@@ -0,0 +1,183 @@
+"""agenthive-mcp - a thin MCP (Model Context Protocol) server exposing
+AgentHive's member-level calls - retrieve_context, log_session,
+create_agent, list_agents, create_task, and list_tasks - as native tools
+for Cursor, Claude Code, and any other MCP client.
+
+This is deliberately a standalone, self-contained wrapper: it makes its
+own plain HTTP calls to a running AgentHive service rather than importing
+anything from the agenthive repo, so this repo has no dependency on that
+one at build, install, or test time - only a runtime one, on the base URL
+of a service you already have running (see
+https://github.com/polarpoint-io/agenthive).
+
+It holds no state and makes no decisions of its own - every tool call is
+a pass-through to the AgentHive HTTP API using the caller's own personal
+token from AGENTHIVE_TOKEN. The member/admin permission split and the
+approval gate (a logged session starts PENDING until reviewed) are both
+enforced entirely server-side; this process can do exactly what that
+token already lets it do over the API directly, nothing more. See
+AgentHive's ADR.md ("Why not build an LLM-request proxy" and
+"Authentication") for the reasoning this follows.
+
+Only [member]-role calls are exposed - the same tier retrieve_context and
+log_session already sit at (see AgentHive's server.py route table).
+Admin-only calls (list_pending/approve/reject, user management,
+auto-approve rules) are deliberately left out: they exist to let a human
+operate the review gate from the review UI or an admin script, and
+turning them into agent-callable tools would let an agent approve or
+reject its own (or another agent's) pending memory, which defeats the
+point of the gate. See AgentHive's ADR.md for why that gate exists.
+
+Transport selection (env vars), matching the rest of the org's MCP
+servers (see polarpoint-io/snyk-mcp):
+    TRANSPORT=stdio (default)   - MCP stdio transport, spawned by your IDE
+    TRANSPORT=http              - SSE/HTTP transport on HTTP_HOST:HTTP_PORT
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import get_config as _get_config
+from .client import request as _request
+
+logger = logging.getLogger("agenthive_mcp")
+
+mcp = FastMCP(
+    name="agenthive",
+    instructions=(
+        "Shared, reviewed memory for a team of coding agents. Call "
+        "retrieve_context before starting work and log_session once you're "
+        "done. Requires AGENTHIVE_URL/AGENTHIVE_TOKEN/AGENTHIVE_TEAM_ID env "
+        "vars set to your own personal AgentHive token."
+    ),
+)
+
+
+@mcp.tool()
+def retrieve_context(anchor: str, hops: int = 2, hub_cutoff: int = 15) -> dict:
+    """Retrieve a bounded neighborhood of this team's reviewed, approved
+    memory around a topic. Call this once at the start of a session,
+    before starting work, so you inherit what teammates already learned
+    instead of rediscovering it. `anchor` is the topic/title to search
+    around (e.g. "Postgres connection pool exhaustion"); `hops` bounds how
+    far the traversal spreads from it (default 2); `hub_cutoff` stops
+    traversal through overly-connected "hub" nodes so one popular node
+    doesn't pull in the whole graph. Returns a `neighborhood` list of
+    memory nodes plus `approx_tokens`, what folding them into context
+    would actually cost."""
+    _, _, team_id = _get_config()
+    return _request(
+        "GET", f"/teams/{team_id}/memory/retrieve",
+        query={"anchor": anchor, "hops": hops, "hub_cutoff": hub_cutoff},
+    )
+
+
+@mcp.tool()
+def log_session(
+    title: str,
+    body: str,
+    tags: list[str] | None = None,
+    links: list[str] | None = None,
+    agent_id: str | None = None,
+    task_id: str | None = None,
+) -> dict:
+    """Log what happened this session as a memory node for the team to
+    reuse. Call this once at the end of a session that learned something
+    worth keeping - a root cause, a fix, a decision, a gotcha. The node
+    starts PENDING and is invisible to retrieve_context until an admin
+    approves it (or it matches an auto-approve rule) - this is a
+    deliberate review gate, not a bug. `title` is a short, searchable
+    summary (this is what future retrieve_context anchors match against);
+    `body` is the actual content; `tags` and `links` are optional and
+    help retrieval and review. `agent_id`/`task_id` are optional ids from
+    create_agent/create_task - attaching them lets an admin auto-approve
+    by agent (see create_auto_approve_rule, admin-only) and lets future
+    retrieval be scoped to a task."""
+    _, _, team_id = _get_config()
+    return _request(
+        "POST", f"/teams/{team_id}/memory",
+        body={
+            "title": title, "body": body, "tags": tags or [], "links": links or [],
+            "agent_id": agent_id, "task_id": task_id,
+        },
+    )
+
+
+@mcp.tool()
+def create_agent(name: str, description: str = "", system_prompt: str = "") -> dict:
+    """Register an agent identity with the team, so logged sessions can be
+    attributed to it (pass the returned id as log_session's `agent_id`)
+    and so an admin can target it with an auto-approve rule. `name` is
+    how it shows up in the review UI; `description` and `system_prompt`
+    are optional context for reviewers."""
+    _, _, team_id = _get_config()
+    return _request(
+        "POST", f"/teams/{team_id}/agents",
+        body={"name": name, "description": description, "system_prompt": system_prompt},
+    )
+
+
+@mcp.tool()
+def list_agents() -> dict:
+    """List the agent identities already registered with this team, e.g.
+    to find an existing agent's id instead of creating a duplicate with
+    create_agent."""
+    _, _, team_id = _get_config()
+    return _request("GET", f"/teams/{team_id}/agents")
+
+
+@mcp.tool()
+def create_task(name: str, description: str = "") -> dict:
+    """Register a task with the team, so logged sessions can be scoped to
+    it (pass the returned id as log_session's `task_id`) - useful when
+    several sessions across one piece of work should be filterable
+    together later. `name` is how it shows up in the review UI;
+    `description` is optional context."""
+    _, _, team_id = _get_config()
+    return _request(
+        "POST", f"/teams/{team_id}/tasks",
+        body={"name": name, "description": description},
+    )
+
+
+@mcp.tool()
+def list_tasks() -> dict:
+    """List the tasks already registered with this team, e.g. to find an
+    existing task's id instead of creating a duplicate with create_task."""
+    _, _, team_id = _get_config()
+    return _request("GET", f"/teams/{team_id}/tasks")
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Console entrypoint. Selects transport based on TRANSPORT env var,
+    same convention as the rest of the org's MCP servers."""
+    logging.basicConfig(
+        level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+    transport = os.environ.get("TRANSPORT", "stdio").lower()
+    if transport == "stdio":
+        logger.info("Starting agenthive-mcp on stdio transport")
+        mcp.run(transport="stdio")
+    elif transport in ("http", "sse"):
+        host = os.environ.get("HTTP_HOST", "0.0.0.0")
+        port = int(os.environ.get("HTTP_PORT", "8000"))
+        mcp.settings.host = host
+        mcp.settings.port = port
+        logger.info("Starting agenthive-mcp on SSE transport at %s:%d", host, port)
+        mcp.run(transport="sse")
+    else:
+        raise SystemExit(f"Unknown TRANSPORT={transport!r}. Use 'stdio' or 'http'.")
+
+
+if __name__ == "__main__":
+    main()

agenthive_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,431 @@
+Metadata-Version: 2.4
+Name: agenthive-mcp
+Version: 1.0.0
+Summary: MCP server exposing AgentHive's shared team memory as native tools for Cursor and Claude Code
+Author: Surj Bains
+License: MIT License
+        
+        Copyright (c) 2026 Surj Bains
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/polarpoint-io/agenthive-mcp
+Project-URL: AgentHive, https://github.com/polarpoint-io/agenthive
+Keywords: mcp,agenthive,memory,coding-agents,platform-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: anyio>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# agenthive-mcp
+
+![agenthive-mcp hero](docs/hero.svg)
+
+[![CI](https://github.com/polarpoint-io/agenthive-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/polarpoint-io/agenthive-mcp/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/polarpoint-io/agenthive-mcp)](LICENSE)
+
+A Model Context Protocol (MCP) server that exposes [AgentHive](https://github.com/polarpoint-io/agenthive)'s shared, reviewed team memory to LLM clients (Claude Desktop, Claude Code, Cursor, VS Code, etc.) - `retrieve_context`, `log_session`, `create_agent`, `list_agents`, `create_task`, and `list_tasks` as native tools, instead of a `CLAUDE.md` / `.cursor/rules` instruction block that calls AgentHive's HTTP API by hand.
+
+> **PyPI**: `pip install agenthive-mcp` &nbsp;·&nbsp; **Image**: `ghcr.io/polarpoint-io/agenthive-mcp:latest` &nbsp;·&nbsp; **Repo**: <https://github.com/polarpoint-io/agenthive-mcp>
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Client integrations](#client-integrations)
+- [Tool reference](#tool-reference)
+- [Wiring an agent up to actually use these tools](#wiring-an-agent-up-to-actually-use-these-tools)
+- [Why a separate repo from AgentHive](#why-a-separate-repo-from-agenthive)
+- [Running from source](#running-from-source)
+- [Development](#development)
+- [Publishing](#publishing)
+- [Security notes](#security-notes)
+
+
+## Quick start
+
+You need an AgentHive team and a personal token first - see [AgentHive's onboarding guide](https://github.com/polarpoint-io/agenthive/blob/main/ONBOARDING.md) if you don't have one yet.
+
+### 1. pip (no Docker)
+
+```bash
+pip install agenthive-mcp
+export AGENTHIVE_URL=https://your-agenthive-host
+export AGENTHIVE_TOKEN=your_personal_token
+export AGENTHIVE_TEAM_ID=your_team_id
+
+agenthive-mcp                                 # stdio
+TRANSPORT=http HTTP_PORT=8000 agenthive-mcp   # HTTP/SSE
+```
+
+### 2. Docker (stdio — launched by your MCP client)
+
+```bash
+docker pull ghcr.io/polarpoint-io/agenthive-mcp:latest
+
+docker run --rm -i \
+  -e AGENTHIVE_URL=https://your-agenthive-host \
+  -e AGENTHIVE_TOKEN=your_personal_token \
+  -e AGENTHIVE_TEAM_ID=your_team_id \
+  ghcr.io/polarpoint-io/agenthive-mcp:latest
+```
+
+### 3. Docker (HTTP/SSE — standalone service)
+
+```bash
+docker run --rm \
+  -p 8000:8000 \
+  -e AGENTHIVE_URL=https://your-agenthive-host \
+  -e AGENTHIVE_TOKEN=your_personal_token \
+  -e AGENTHIVE_TEAM_ID=your_team_id \
+  -e TRANSPORT=http \
+  ghcr.io/polarpoint-io/agenthive-mcp:latest
+# SSE endpoint: http://localhost:8000/sse
+```
+
+Use your own token, not a shared or admin one - whatever it can do (`member` or `admin`) is what this server can do on your behalf, nothing more or less (see [Security notes](#security-notes)).
+
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AGENTHIVE_URL` | yes | — | Base URL of a running AgentHive service |
+| `AGENTHIVE_TOKEN` | yes | — | Your personal AgentHive token |
+| `AGENTHIVE_TEAM_ID` | yes | — | Your AgentHive team id |
+| `TRANSPORT` | no | `stdio` | `stdio` or `http` |
+| `HTTP_HOST` | no | `0.0.0.0` | Bind host (HTTP mode) |
+| `HTTP_PORT` | no | `8000` | Bind port (HTTP mode) |
+| `LOG_LEVEL` | no | `INFO` | Python log level |
+
+See [`.env.example`](.env.example) for a copy-pasteable template.
+
+
+## Client integrations
+
+Each client supports two transport options — **pip** (recommended, no Docker required) or **Docker**.
+
+```bash
+# Install once
+pip install agenthive-mcp
+```
+
+---
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
+
+**pip (recommended)**
+```json
+{
+  "mcpServers": {
+    "agenthive": {
+      "command": "agenthive-mcp",
+      "env": {
+        "AGENTHIVE_URL": "https://your-agenthive-host",
+        "AGENTHIVE_TOKEN": "your_personal_token",
+        "AGENTHIVE_TEAM_ID": "your_team_id"
+      }
+    }
+  }
+}
+```
+
+**Docker**
+```json
+{
+  "mcpServers": {
+    "agenthive": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-e", "AGENTHIVE_URL", "-e", "AGENTHIVE_TOKEN", "-e", "AGENTHIVE_TEAM_ID",
+        "ghcr.io/polarpoint-io/agenthive-mcp:latest"
+      ],
+      "env": {
+        "AGENTHIVE_URL": "https://your-agenthive-host",
+        "AGENTHIVE_TOKEN": "your_personal_token",
+        "AGENTHIVE_TEAM_ID": "your_team_id"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing. You should see a hammer icon in the chat confirming the `agenthive` server is connected with all 6 tools available.
+
+---
+
+### Claude Code
+
+**pip (recommended)**
+```bash
+pip install agenthive-mcp
+
+claude mcp add agenthive -- agenthive-mcp
+# then export your config before running claude:
+export AGENTHIVE_URL=https://your-agenthive-host
+export AGENTHIVE_TOKEN=your_personal_token
+export AGENTHIVE_TEAM_ID=your_team_id
+```
+
+**Docker**
+```bash
+claude mcp add agenthive -- docker run --rm -i \
+  -e AGENTHIVE_URL -e AGENTHIVE_TOKEN -e AGENTHIVE_TEAM_ID \
+  ghcr.io/polarpoint-io/agenthive-mcp:latest
+```
+
+Or a plain `.mcp.json` in the repo root works too - same shape as Claude Desktop's config above.
+
+---
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+**pip (recommended)**
+```json
+{
+  "mcpServers": {
+    "agenthive": {
+      "command": "agenthive-mcp",
+      "env": {
+        "AGENTHIVE_URL": "https://your-agenthive-host",
+        "AGENTHIVE_TOKEN": "your_personal_token",
+        "AGENTHIVE_TEAM_ID": "your_team_id"
+      }
+    }
+  }
+}
+```
+
+**Docker**
+```json
+{
+  "mcpServers": {
+    "agenthive": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i",
+               "-e", "AGENTHIVE_URL", "-e", "AGENTHIVE_TOKEN", "-e", "AGENTHIVE_TEAM_ID",
+               "ghcr.io/polarpoint-io/agenthive-mcp:latest"],
+      "env": {
+        "AGENTHIVE_URL": "https://your-agenthive-host",
+        "AGENTHIVE_TOKEN": "your_personal_token",
+        "AGENTHIVE_TEAM_ID": "your_team_id"
+      }
+    }
+  }
+}
+```
+
+---
+
+### VS Code (Continue)
+
+Edit `~/.continue/config.json`:
+
+**pip (recommended)**
+```json
+{
+  "mcpServers": [{
+    "name": "agenthive",
+    "command": "agenthive-mcp",
+    "env": {
+      "AGENTHIVE_URL": "https://your-agenthive-host",
+      "AGENTHIVE_TOKEN": "your_personal_token",
+      "AGENTHIVE_TEAM_ID": "your_team_id"
+    }
+  }]
+}
+```
+
+---
+
+### HTTP / SSE (remote or shared server)
+
+If you prefer to run the server as a persistent HTTP service rather than a subprocess - still bound to whichever token you start it with, this is a transport choice, not a different auth model:
+
+```bash
+# pip
+pip install agenthive-mcp
+AGENTHIVE_URL=... AGENTHIVE_TOKEN=... AGENTHIVE_TEAM_ID=... TRANSPORT=http HTTP_PORT=8000 agenthive-mcp
+
+# Docker
+docker run --rm -p 8000:8000 \
+  -e AGENTHIVE_URL=... -e AGENTHIVE_TOKEN=... -e AGENTHIVE_TEAM_ID=... \
+  -e TRANSPORT=http \
+  ghcr.io/polarpoint-io/agenthive-mcp:latest
+```
+
+Then point your MCP client at `http://localhost:8000/sse`.
+
+
+## Tool reference
+
+Every tool here is a **member**-role AgentHive call - the same tier your personal token already grants over the API directly. Admin-only calls (`list_pending`/`approve`/`reject`, user management, auto-approve rules) are deliberately not exposed as tools: they exist so a *human* operates the review gate from the review UI or an admin script, and turning them into agent-callable tools would let an agent approve or reject its own pending memory, which defeats the point of the gate. See AgentHive's `ADR.md` for why the gate exists, and its README for those calls.
+
+| Tool | Description |
+|---|---|
+| `retrieve_context` | Bounded neighborhood of this team's reviewed, approved memory around a topic (`anchor`, `hops=2`, `hub_cutoff=15`) |
+| `log_session` | Log what happened this session as a memory node (`title`, `body`, `tags`, `links`, `agent_id`, `task_id`) - starts `pending` |
+| `create_agent` | Register an agent identity (`name`, `description`, `system_prompt`) so sessions can be attributed to it |
+| `list_agents` | List agent identities already registered with the team |
+| `create_task` | Register a task (`name`, `description`) so sessions can be scoped to it |
+| `list_tasks` | List tasks already registered with the team |
+
+
+## Wiring an agent up to actually use these tools
+
+Tools existing in the tool list doesn't make an agent call them unprompted - it needs a line telling it when.
+
+If the repo uses polarpoint-io's platform-standards `AGENTS.md` template (see [`ai-capabilities/platform-standards/templates/default-agents-md.md`](https://github.com/polarpoint-io/ai-capabilities/blob/main/platform-standards/templates/default-agents-md.md)), add it to **Zone 3** ("Repo-specific notes" - free, team-owned, and explicitly meant for "context about the domain, gotchas, preferred libraries, links to runbooks"):
+
+```markdown
+## AgentHive
+
+Before starting work, call `retrieve_context` with a short description of
+the task. When you're done, call `log_session` summarizing what you did
+and learned.
+```
+
+Team-specific conventions (which tags to use, the team's `AGENTHIVE_TEAM_ID`) belong in Zone 2 instead - guarded, but team-owned, meant to extend Zone 1 rather than override it. Don't put either in Zone 1: that's platform-locked, and making AgentHive retrieval mandatory org-wide is a bigger call than one repo should make on its own - it would need a PR to `ai-capabilities` and platform-team review.
+
+Repos without that template yet can use a plain `CLAUDE.md` / `.cursor/rules` line instead - same content, just a different file.
+
+
+## Why a separate repo from AgentHive
+
+This started as a module inside the AgentHive repo itself, then moved out: it has its own dependency (`mcp`), its own release cadence (an IDE integration changes on its own schedule, unrelated to the service's), and no reason to need AgentHive's own container image, Helm chart, or CI matrix rebuilt every time it changes - or vice versa.
+
+It's self-contained: it makes its own plain HTTP calls to a running AgentHive service rather than importing anything from the `agenthive` repo, so this repo has no dependency on that one at build, install, or test time - only a runtime one, on the base URL of a service you already have running.
+
+
+## Running from source
+
+```bash
+git clone git@github.com:polarpoint-io/agenthive-mcp.git
+cd agenthive-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]
+
+export AGENTHIVE_URL=...
+export AGENTHIVE_TOKEN=...
+export AGENTHIVE_TEAM_ID=...
+
+agenthive-mcp                                 # stdio
+TRANSPORT=http HTTP_PORT=8000 agenthive-mcp   # HTTP/SSE
+```
+
+Or via the Makefile:
+
+```bash
+make dev       # install with dev extras
+make test      # pytest
+make lint      # ruff check
+make run       # stdio
+make run-http  # HTTP/SSE on :8000
+make docker    # build the image locally
+```
+
+
+## Development
+
+```bash
+make dev
+make test
+make lint
+```
+
+The test suite (`tests/test_tools.py`) drives the server as a real subprocess over real MCP stdio, using a real `mcp.ClientSession` - nothing mocked at the protocol layer. The AgentHive side is a small local fake (`tests/fake_agenthive.py`), not the real service, since this repo shouldn't need AgentHive itself checked out to test its own HTTP plumbing; AgentHive's own approval-gate/retrieval/auth behavior is already covered by its own test suite, in its own repo, against the real `server.py`. Try this server against a real AgentHive instance manually if you want to confirm the whole chain end to end.
+
+Adding a new tool:
+
+1. Add a `@mcp.tool()` function in `src/agenthive_mcp/server.py`, calling `_request()` from `client.py`. Only for a **member**-role AgentHive endpoint - see [Tool reference](#tool-reference).
+2. Add a matching route to `tests/fake_agenthive.py` if the endpoint isn't already covered.
+3. Add a test in `tests/test_tools.py` using the existing `stdio_client`/`ClientSession` pattern.
+
+See [`AGENTS.md`](AGENTS.md) for deeper contribution guidance.
+
+
+## Publishing
+
+Releases are fully automated via [semantic-release](https://semantic-release.gitbook.io/) - no manual tagging needed.
+
+### How it works
+
+Every push to `main` runs the CI pipeline:
+
+1. **Test** — lint (`ruff`) + pytest across Python 3.10 / 3.11 / 3.12
+2. **Docker** — builds and pushes the image to GHCR
+3. **Release** — semantic-release analyses conventional commits, bumps the version, updates `CHANGELOG.md`, publishes to PyPI, and creates a GitHub Release
+
+A release only happens when commits contain a `feat:`, `fix:`, or breaking-change - `chore:`, `docs:`, `ci:` commits don't trigger one.
+
+### Docker image tags
+
+| Tag | When pushed |
+|---|---|
+| `latest` | Every merge to `main` |
+| `sha-<short>` | Every merge to `main` |
+| `1.2.3` / `1.2` | On a semantic-release version bump |
+
+### Required GitHub secrets
+
+| Secret | Description |
+|---|---|
+| `POL_GH_TOKEN` | Personal access token with `repo` + `write:packages` scope |
+| `PYPI_TOKEN` | PyPI API token for the `agenthive-mcp` project |
+
+Add both at: **GitHub repo → Settings → Secrets and variables → Actions**.
+
+### Commit conventions
+
+```
+feat: add new tool          → minor version bump (0.x.0)
+fix: correct response shape → patch bump        (0.0.x)
+feat!: breaking change      → major bump        (x.0.0)
+chore/docs/ci/test          → no release
+```
+
+
+## Security notes
+
+- The container runs as a non-root user (`uid 10001`).
+- `AGENTHIVE_TOKEN` is read from env vars only - never written to disk.
+- This process holds no state and makes no decisions of its own - every tool call is a pass-through to AgentHive's HTTP API using the caller's own token. It can do exactly what that token already lets it do over the API directly, nothing more.
+- Admin-only calls (the review gate, user management, auto-approve rules) are deliberately **not** exposed as tools - see [Tool reference](#tool-reference).
+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agenthive_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agenthive_mcp/__init__.py,sha256=s7GSsGyfBQfN0zUQdL9AcwGv-AvruCN8PWZZaGyGRoU,103
+agenthive_mcp/client.py,sha256=UqRhRLNtQjYVGk14sYJHTd99LeDUG_qHlx5gJy5FnDM,2863
+agenthive_mcp/server.py,sha256=gNx0z8UrD6wHojC-N9dAmq6hUIqrtKzjzUP6HZJlpJc,7713
+agenthive_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=tzIxURH0v71uEMtkuuEZu45QTT-kNRh6xveRCsxVh-E,1067
+agenthive_mcp-1.0.0.dist-info/METADATA,sha256=Btt0eTBMhlDdeDi6Kiy3zN6qPLcz9FKCnc5fBBSQQVE,16144
+agenthive_mcp-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agenthive_mcp-1.0.0.dist-info/entry_points.txt,sha256=w3H2dzh-_Zyxq64EXmVLm-TKV6lCCdsz8Y3ZW4W65bc,60
+agenthive_mcp-1.0.0.dist-info/top_level.txt,sha256=48SkxM4krxsU7cdWwUMObOUqKAznIFrHURzz_a1CkQw,14
+agenthive_mcp-1.0.0.dist-info/RECORD,,

agenthive_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agenthive_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agenthive-mcp = agenthive_mcp.server:main

agenthive_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surj Bains
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agenthive_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agenthive_mcp