argile-mcp 0.1.1__tar.gz

argile_mcp-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.env.keys
+*.egg-info/
+dist/
+build/
+.claude/

argile_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: argile-mcp
+Version: 0.1.1
+Summary: MCP server to talk with the Argile lead bot from Claude
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: logfire[httpx]>=4
+Requires-Dist: mcp>=1.2
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.7

argile_mcp-0.1.1/README.md

@@ -0,0 +1,139 @@
+# argile-mcp
+
+MCP server to talk with the Argile lead bot directly from Claude (Claude Code, Claude Desktop, or any MCP client).
+
+It wraps the bot's web chat API (`https://bot.argile.ai`) so Claude can hold conversations with the bot — which in turn creates leads, quotes, catalogs and projects in the Argile CRM on your behalf.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `chat(message, conversation_id?)` | Send a message to the bot, get the full reply. Omit `conversation_id` to start a new conversation; reuse the returned id to continue it. |
+| `list_conversations(limit?)` | List your recent conversations (title, counts, timestamps). |
+| `get_conversation(conversation_id)` | Full transcript + linked CRM objects (leads, quotes, …) with direct-access URLs. |
+| `clear_history()` | Clear the active conversation context (destructive). |
+
+## Logging in
+
+No token copying needed — the server ships a device-flow login that reuses
+the bot's magic-link page:
+
+- **From Claude**: just ask to talk to the bot; if you're not logged in, Claude
+  calls `start_login`, gives you a link to open (you sign in with your Argile
+  account and click *Autoriser*), then `complete_login` stores the token in
+  `~/.argile/credentials.json`.
+- **From a terminal**: `uvx … argile-mcp login` (or `uv run argile-mcp login`
+  from a checkout) prints the link and waits for you to authorize.
+
+## Configuration
+
+| Env var | Required | Description |
+|---|---|---|
+| `ARGILE_TOKEN` | no | Argile API bearer token; overrides the stored login. Useful for CI. |
+| `ARGILE_BOT_URL` | no | Bot base URL, defaults to `https://bot.argile.ai`. |
+| `ARGILE_CREDENTIALS_PATH` | no | Where the login flow stores the token, defaults to `~/.argile/credentials.json`. |
+| `ARGILE_LOG_LEVEL` | no | Stderr log level of the server process, defaults to `INFO`. |
+| `LOGFIRE_TOKEN` | no | Set to export traces to [Logfire](https://logfire.pydantic.dev) (MCP tool calls, bot HTTP calls, chat spans). Unset → no telemetry leaves the machine. |
+
+## Logging & telemetry
+
+stdout carries the MCP protocol, so the server only ever logs to **stderr**.
+With `LOGFIRE_TOKEN` set (we use it internally; end users don't need it),
+Logfire traces every MCP tool call and bot HTTP request, plus an
+`argile-bot chat` span per turn with `tools_used` / `reply_chars` /
+`chart_count` attributes. Logs and spans never contain message or reply
+content — only sizes, ids and tool names.
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/). The server runs on stdio and is published to PyPI as [`argile-mcp`](https://pypi.org/project/argile-mcp/) (see *Releasing* below).
+
+### Claude Code
+
+```bash
+claude mcp add argile-bot -- uvx argile-mcp
+```
+
+Or per-project, in `.mcp.json` (see [`examples/mcp.json`](examples/mcp.json)):
+
+```json
+{
+  "mcpServers": {
+    "argile-bot": {
+      "command": "uvx",
+      "args": ["argile-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add the same server block to `~/Library/Application Support/Claude/claude_desktop_config.json` (see [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)).
+
+### From a local checkout (development)
+
+```bash
+claude mcp add argile-bot \
+  -- uv run --directory /path/to/argile-bot/mcp argile-mcp
+```
+
+## Example prompts
+
+Once installed, just ask Claude:
+
+- *"Demande au bot Argile de lister mes conversations récentes."*
+- *"Via le bot Argile : crée un lead pour Marie Dupont, 12 rue des Lilas à Lyon, projet pompe à chaleur."*
+- *"Reprends la conversation `<id>` avec le bot et demande où en est le devis."*
+- *"Montre-moi le transcript de ma dernière conversation avec le bot et les objets CRM liés."*
+
+A typical `chat` result:
+
+```json
+{
+  "reply": "J'ai créé le lead Marie Dupont ✅ …",
+  "conversation_id": "0e8f7c3a-…",
+  "active_lead_id": "lead_123",
+  "tools_used": ["create_lead"],
+  "chart_count": 0
+}
+```
+
+## Development
+
+The package is a uv workspace member; its tests live next to it in
+`mcp/tests/` (also collected by a plain `uv run pytest` from the repo root)
+and include contract tests that bind the MCP client to the real chat router,
+so API drift fails CI.
+
+```bash
+uv sync
+uv run pytest mcp/tests
+```
+
+Smoke-test against the real bot (after `argile-mcp login` or with `ARGILE_TOKEN` set):
+
+```bash
+uv run python mcp/examples/smoke.py "Bonjour, qui es-tu ?"
+```
+
+Inspect the server interactively with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector uv run argile-mcp
+```
+
+## Releasing
+
+Bump `version` in `mcp/pyproject.toml`, then push a matching tag:
+
+```bash
+git tag mcp-v0.1.0 && git push origin mcp-v0.1.0
+```
+
+The `release-mcp.yml` workflow runs the MCP tests, builds the package and
+publishes it to PyPI via trusted publishing. One-time setup on pypi.org:
+project **argile-mcp** → *Publishing* → add the GitHub publisher
+(`argile-ai/argile-bot`, workflow `release-mcp.yml`, environment `pypi`),
+and create the matching `pypi` environment in this repo's GitHub settings.
+Only the built wheel goes public — the repo stays private.

argile_mcp-0.1.1/examples/claude_desktop_config.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "argile-bot": {
+      "command": "uvx",
+      "args": [
+        "argile-mcp"
+      ]
+    }
+  }
+}

argile_mcp-0.1.1/examples/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "argile-bot": {
+      "command": "uvx",
+      "args": [
+        "argile-mcp"
+      ]
+    }
+  }
+}

argile_mcp-0.1.1/examples/smoke.py

@@ -0,0 +1,44 @@
+"""Smoke test against the real bot: one chat round-trip through the MCP server.
+
+Usage (from the repo root, after `argile-mcp login` or with ARGILE_TOKEN set):
+    uv run python mcp/examples/smoke.py "Bonjour, qui es-tu ?"
+
+Spawns the MCP server as a subprocess over stdio (exactly how Claude runs it),
+lists its tools, sends one chat message and prints the structured reply.
+"""
+
+import asyncio
+import json
+import os
+import sys
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+async def main() -> None:
+    message = sys.argv[1] if len(sys.argv) > 1 else "Bonjour, qui es-tu ?"
+
+    params = StdioServerParameters(
+        command="uv", args=["run", "argile-mcp"], env=dict(os.environ)
+    )
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = (await session.list_tools()).tools
+            print(f"tools: {[tool.name for tool in tools]}")
+
+            print(f"> {message}")
+            result = await session.call_tool("chat", {"message": message})
+            if result.isError:
+                sys.exit(f"chat failed: {result.content[0].text}")
+            print(
+                json.dumps(
+                    json.loads(result.content[0].text), indent=2, ensure_ascii=False
+                )
+            )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

argile_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "argile-mcp"
+version = "0.1.1"
+description = "MCP server to talk with the Argile lead bot from Claude"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.2",
+    "httpx>=0.28",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.7",
+    "logfire[httpx]>=4",
+]
+
+[project.scripts]
+argile-mcp = "argile_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argile_mcp"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

argile_mcp-0.1.1/src/argile_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""MCP server for talking with the Argile lead bot from Claude."""
+
+from argile_mcp.client import ArgileBotClient
+from argile_mcp.config import Settings
+from argile_mcp.errors import ArgileBotError
+from argile_mcp.schemas import ChatResult
+
+__all__ = ["ArgileBotClient", "ArgileBotError", "ChatResult", "Settings"]

argile_mcp-0.1.1/src/argile_mcp/auth.py

@@ -0,0 +1,66 @@
+"""Device-flow login against the bot's /auth/mcp endpoints.
+
+Mirrors the bot's magic-link flow: start a login session, send the user to
+the returned URL to authorize in a browser (Clerk), then poll until the bot
+hands out the token — exactly once.
+"""
+
+import asyncio
+import logging
+
+import httpx
+
+from argile_mcp.errors import ArgileBotError
+from argile_mcp.schemas import DeviceAuthStart
+
+logger = logging.getLogger(__name__)
+
+POLL_INTERVAL = 2.0
+POLL_TIMEOUT = 180.0
+
+
+async def start_login(
+    base_url: str, transport: httpx.AsyncBaseTransport | None = None
+) -> DeviceAuthStart:
+    """Open a login session; the user must authorize on the returned URL."""
+    async with httpx.AsyncClient(timeout=30.0, transport=transport) as client:
+        response = await client.post(f"{base_url.rstrip('/')}/auth/mcp/start")
+        if response.status_code != 200:
+            raise ArgileBotError(
+                f"HTTP {response.status_code} from bot: {response.text[:500]}"
+            )
+        start = DeviceAuthStart.model_validate(response.json())
+        logger.info("login session opened at %s", base_url)
+        return start
+
+
+async def poll_token(
+    base_url: str,
+    poll_key: str,
+    timeout: float = POLL_TIMEOUT,
+    interval: float = POLL_INTERVAL,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> str:
+    """Wait for the user to authorize, then collect the token (one-time)."""
+    deadline = asyncio.get_running_loop().time() + timeout
+    async with httpx.AsyncClient(timeout=30.0, transport=transport) as client:
+        while True:
+            response = await client.get(
+                f"{base_url.rstrip('/')}/auth/mcp/token",
+                params={"poll_key": poll_key},
+            )
+            if response.status_code == 200:
+                logger.info("login authorized, token received")
+                return response.json()["token"]
+            if response.status_code != 202:
+                logger.warning("login poll failed: HTTP %d", response.status_code)
+                raise ArgileBotError(
+                    f"Login failed (HTTP {response.status_code}): {response.text[:500]}"
+                )
+            if asyncio.get_running_loop().time() >= deadline:
+                logger.warning("login timed out after %.0fs", timeout)
+                raise ArgileBotError(
+                    "Login not completed in time. Start a new login and open "
+                    "the URL in your browser."
+                )
+            await asyncio.sleep(interval)

argile_mcp-0.1.1/src/argile_mcp/client.py

@@ -0,0 +1,145 @@
+"""Thin async HTTP client over the Argile bot's web endpoints.
+
+Logging never includes message or reply content (user data) — only sizes,
+ids and tool names.
+"""
+
+import logging
+from typing import Any
+
+import httpx
+import logfire
+from pydantic import TypeAdapter
+
+from argile_mcp.config import Settings
+from argile_mcp.credentials import load_token
+from argile_mcp.errors import ArgileBotError
+from argile_mcp.schemas import (
+    ChatResult,
+    ConversationDetail,
+    ConversationSummary,
+    StatusResult,
+)
+from argile_mcp.sse import fold_event, parse_sse_frame
+
+logger = logging.getLogger(__name__)
+
+_SUMMARIES = TypeAdapter(list[ConversationSummary])
+
+
+class ArgileBotClient:
+    """Client for the bot's chat and conversations API.
+
+    `transport` is injectable so tests can bind the client straight to the
+    bot's ASGI app without a network hop.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        settings = Settings()
+        self.base_url = (base_url or settings.argile_bot_url).rstrip("/")
+        self.token = (
+            token
+            or settings.argile_token
+            or load_token(settings.argile_credentials_path)
+            or ""
+        )
+        self.transport = transport
+        self.chat_timeout = httpx.Timeout(10.0, read=settings.chat_read_timeout)
+        if not self.token:
+            raise ArgileBotError(
+                "Not logged in. Use the start_login/complete_login tools (or "
+                "run `argile-mcp login`), or set ARGILE_TOKEN."
+            )
+
+    def _http(self, timeout: httpx.Timeout | float) -> httpx.AsyncClient:
+        return httpx.AsyncClient(timeout=timeout, transport=self.transport)
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"}
+
+    async def chat(
+        self, message: str, conversation_id: str | None = None
+    ) -> ChatResult:
+        """Send one message and read the streamed reply to completion."""
+        form: dict[str, str] = {"message": message}
+        if conversation_id:
+            form["conversation_id"] = conversation_id
+
+        result = ChatResult()
+        logger.info(
+            "chat turn started: conversation=%s message_chars=%d",
+            conversation_id or "new",
+            len(message),
+        )
+        with logfire.span(
+            "argile-bot chat",
+            conversation_id=conversation_id,
+            message_chars=len(message),
+        ) as span:
+            async with self._http(self.chat_timeout) as client:
+                async with client.stream(
+                    "POST",
+                    f"{self.base_url}/chat/stream",
+                    data=form,
+                    headers=self._headers,
+                ) as response:
+                    if response.status_code != 200:
+                        body = (await response.aread()).decode(errors="replace")
+                        logger.warning(
+                            "chat turn failed: HTTP %d", response.status_code
+                        )
+                        raise ArgileBotError(
+                            f"HTTP {response.status_code} from bot: {body[:500]}"
+                        )
+                    async for line in response.aiter_lines():
+                        event = parse_sse_frame(line)
+                        if event is not None:
+                            fold_event(result, event)
+            span.set_attribute("tools_used", result.tools_used)
+            span.set_attribute("reply_chars", len(result.reply))
+            span.set_attribute("chart_count", result.chart_count)
+        logger.info(
+            "chat turn done: conversation=%s tools=%s reply_chars=%d charts=%d",
+            result.conversation_id,
+            result.tools_used,
+            len(result.reply),
+            result.chart_count,
+        )
+        return result
+
+    async def _get_json(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        async with self._http(30.0) as client:
+            response = await client.get(
+                f"{self.base_url}{path}", params=params, headers=self._headers
+            )
+            if response.status_code != 200:
+                logger.warning("GET %s failed: HTTP %d", path, response.status_code)
+                raise ArgileBotError(
+                    f"HTTP {response.status_code} from bot: {response.text[:500]}"
+                )
+            return response.json()
+
+    async def list_conversations(self, limit: int = 20) -> list[ConversationSummary]:
+        payload = await self._get_json("/conversations", params={"limit": limit})
+        return _SUMMARIES.validate_python(payload)
+
+    async def get_conversation(self, conversation_id: str) -> ConversationDetail:
+        payload = await self._get_json(f"/conversations/{conversation_id}")
+        return ConversationDetail.model_validate(payload)
+
+    async def clear_history(self) -> StatusResult:
+        async with self._http(30.0) as client:
+            response = await client.delete(
+                f"{self.base_url}/chat/history", headers=self._headers
+            )
+            if response.status_code != 200:
+                raise ArgileBotError(
+                    f"HTTP {response.status_code} from bot: {response.text[:500]}"
+                )
+            return StatusResult.model_validate(response.json())

argile_mcp-0.1.1/src/argile_mcp/config.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """MCP server configuration, read from the environment (or a .env file).
+
+    Instantiate at client construction time, not import time, so each server
+    process (and each test) picks up the current environment.
+    """
+
+    # extra="ignore": a .env may also hold the bot's own variables (e.g. when
+    # running from the argile-bot checkout).
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}
+
+    # Argile API bearer token of the user the bot acts for. Optional when a
+    # token has been stored by the login flow (see credentials.py).
+    argile_token: str = ""
+
+    # Where the login flow stores the token it obtains.
+    argile_credentials_path: Path = Path.home() / ".argile" / "credentials.json"
+
+    # Bot base URL.
+    argile_bot_url: str = "https://bot.argile.ai"
+
+    # Reading the whole SSE stream can take a while: the agent may run
+    # several CRM tool calls before answering.
+    chat_read_timeout: float = 300.0
+
+    # Stderr log level for the server process. Logfire export is controlled
+    # separately by LOGFIRE_TOKEN (unset → no telemetry leaves the machine).
+    argile_log_level: str = "INFO"

argile_mcp-0.1.1/src/argile_mcp/credentials.py

@@ -0,0 +1,25 @@
+"""Local storage for the token obtained by the login flow."""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def load_token(path: Path) -> str | None:
+    """Read the stored token, or None when absent or unreadable."""
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    token = data.get("token") if isinstance(data, dict) else None
+    return token if isinstance(token, str) and token else None
+
+
+def save_token(path: Path, token: str) -> None:
+    """Store the token, owner-readable only."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"token": token}))
+    path.chmod(0o600)
+    logger.info("token stored in %s", path)

argile_mcp-0.1.1/src/argile_mcp/errors.py

@@ -0,0 +1,2 @@
+class ArgileBotError(Exception):
+    """The bot returned an error (HTTP or in-stream ``error`` event)."""

argile_mcp-0.1.1/src/argile_mcp/schemas.py

@@ -0,0 +1,152 @@
+"""Pydantic models for the bot's SSE wire contract and MCP tool results."""
+
+from datetime import datetime
+from typing import Annotated, Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+# Enum-ish fields (channel, role, linked-object type) and chart specs are kept
+# open (str / dict) on purpose: the bot owns those vocabularies and may grow
+# them; the MCP passes them through. Everything structural is typed, and the
+# contract tests in argile-bot pin these models to the real routers.
+
+
+class TextEvent(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class ToolEvent(BaseModel):
+    type: Literal["tool"]
+    name: str
+
+
+class ChartEvent(BaseModel):
+    type: Literal["chart"]
+    spec: dict[str, Any] = Field(default_factory=dict)
+
+
+class DoneEvent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    type: Literal["done"]
+    conversation_id: str | None = Field(default=None, alias="conversationId")
+    active_lead_id: str | None = Field(default=None, alias="activeLeadId")
+
+
+class ErrorEvent(BaseModel):
+    type: Literal["error"]
+    message: str = "Unknown bot error"
+    detail: str | None = None
+
+
+StreamEvent = Annotated[
+    TextEvent | ToolEvent | ChartEvent | DoneEvent | ErrorEvent,
+    Field(discriminator="type"),
+]
+
+
+class ChatResult(BaseModel):
+    """The bot's reply to one chat turn, accumulated from the SSE stream.
+
+    `charts` holds the raw chart specs for callers that want them but is
+    excluded from dumps — MCP results only carry the count.
+    """
+
+    reply: str = ""
+    conversation_id: str | None = None
+    active_lead_id: str | None = None
+    tools_used: list[str] = Field(default_factory=list)
+    charts: list[dict[str, Any]] = Field(default_factory=list, exclude=True)
+
+    @computed_field
+    @property
+    def chart_count(self) -> int:
+        return len(self.charts)
+
+
+# --- /conversations payloads (mirrors src/conversations.py in argile-bot) ----
+# extra="allow" so new API fields flow through to the model instead of being
+# silently dropped.
+
+
+class TextStep(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class ToolStep(BaseModel):
+    type: Literal["tool"]
+    name: str
+
+
+class ChartStep(BaseModel):
+    type: Literal["chart"]
+    spec: dict[str, Any] = Field(default_factory=dict)
+
+
+TranscriptStep = Annotated[TextStep | ToolStep | ChartStep, Field(discriminator="type")]
+
+
+class LinkedObject(BaseModel):
+    """A CRM object linked to a conversation, with a direct-access URL."""
+
+    model_config = ConfigDict(extra="allow")
+
+    id: UUID
+    type: str
+    object_id: str
+    label: str | None = None
+    url: str | None = None
+    created_at: datetime
+
+
+class Message(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: UUID
+    role: str
+    content: str
+    steps: list[TranscriptStep] | None = None
+    attachment_url: str | None = None
+    created_at: datetime
+
+
+class ConversationBase(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: UUID
+    sender_id: str
+    channel: str
+    lead_id: str | None = None
+    user_email: str | None = None
+    created_at: datetime
+    last_message_at: datetime
+    ended_at: datetime | None = None
+
+
+class ConversationSummary(ConversationBase):
+    title: str
+    message_count: int
+    linked_object_count: int
+
+
+class ConversationDetail(ConversationBase):
+    messages: list[Message]
+    linked_objects: list[LinkedObject]
+
+
+class StatusResult(BaseModel):
+    status: str
+
+
+class DeviceAuthStart(BaseModel):
+    """Handshake material returned by the bot's /auth/mcp/start endpoint.
+
+    `poll_key` is a one-time secret: hand it back to `complete_login` after
+    the user has authorized on `login_url`.
+    """
+
+    poll_key: str
+    login_url: str