chattermate-cli 0.2.0__py3-none-any.whl

chattermate_cli/mcp_server.py

@@ -0,0 +1,253 @@
+"""
+ChatterMate - MCP Server
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>
+
+------------------------------------------------------------------------------
+ChatterMate MCP server (stdio). Exposes ChatterMate configuration to AI agents.
+
+Configuration via environment:
+  CHATTERMATE_TOKEN     A personal access token (cmat_...) — required.
+  CHATTERMATE_API_URL   API base URL (default https://api.chattermate.chat).
+                        Set to http://localhost:8000 for a local backend.
+
+Run:  chattermate-mcp        (or: uvx --from chattermate-cli chattermate-mcp)
+"""
+
+from typing import Any, Dict, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from . import config
+from .client import ChatterMateError, Client
+
+mcp = FastMCP("chattermate")
+
+
+def _client() -> Client:
+    api_url = config.resolve_api_url()
+    token = config.resolve_token()
+    if not token:
+        raise ChatterMateError(
+            "No credentials. Set CHATTERMATE_TOKEN to a personal access token (cmat_...)."
+        )
+    cfg = config.load_config()
+    return Client(
+        api_url=api_url,
+        token=token,
+        refresh_token=cfg.get("refresh_token"),
+    )
+
+
+def _org_id(client: Client) -> Optional[str]:
+    org = config.load_config().get("organization_id")
+    if org:
+        return org
+    try:
+        me = client.whoami()
+    except ChatterMateError:
+        return None
+    return me.get("organization_id") if isinstance(me, dict) else None
+
+
+def _call(fn) -> Any:
+    """Run an API call, returning a structured error dict instead of raising."""
+    try:
+        return fn()
+    except ChatterMateError as e:
+        return {"error": str(e), "status_code": e.status_code}
+
+
+# -- read-only tools -------------------------------------------------------
+
+@mcp.tool()
+def whoami() -> Any:
+    """Return the authenticated user (id, email, organization, role)."""
+    client = _client()
+    return _call(client.whoami)
+
+
+@mcp.tool()
+def list_agents() -> Any:
+    """List all AI agents in the organization."""
+    client = _client()
+    return _call(client.list_agents)
+
+
+@mcp.tool()
+def get_agent(agent_id: str) -> Any:
+    """Get a single agent by id."""
+    client = _client()
+    return _call(lambda: client.get_agent(agent_id))
+
+
+@mcp.tool()
+def get_workflow(agent_id: str) -> Any:
+    """Get the workflow attached to an agent."""
+    client = _client()
+    return _call(lambda: client.get_workflow_for_agent(agent_id))
+
+
+@mcp.tool()
+def get_workflow_nodes(workflow_id: str) -> Any:
+    """Get all nodes and connections for a workflow."""
+    client = _client()
+    return _call(lambda: client.get_workflow_nodes(workflow_id))
+
+
+@mcp.tool()
+def list_knowledge(agent_id: str) -> Any:
+    """List knowledge sources linked to an agent."""
+    client = _client()
+    return _call(lambda: client.list_knowledge_for_agent(agent_id))
+
+
+@mcp.tool()
+def get_ingestion_status(queue_id: int) -> Any:
+    """Get the status of a knowledge ingestion queue item."""
+    client = _client()
+    return _call(lambda: client.knowledge_queue_status(queue_id))
+
+
+# -- mutating tools --------------------------------------------------------
+
+@mcp.tool()
+def create_agent(
+    name: str,
+    agent_type: str = "CUSTOM",
+    instructions: Optional[List[str]] = None,
+    description: Optional[str] = None,
+    display_name: Optional[str] = None,
+) -> Any:
+    """
+    Create an AI agent. agent_type is one of customer_support, sales, tech_support,
+    general, custom (case-insensitive). The organization is taken from the authenticated user.
+    """
+    client = _client()
+    org_id = _org_id(client)
+    if not org_id:
+        return {"error": "Could not determine organization for the current credentials."}
+    payload: Dict[str, Any] = {
+        "name": name,
+        "agent_type": agent_type.lower(),
+        "instructions": instructions or [f"You are {name}, a helpful assistant."],
+        "organization_id": org_id,
+    }
+    if description is not None:
+        payload["description"] = description
+    if display_name is not None:
+        payload["display_name"] = display_name
+    return _call(lambda: client.create_agent(payload))
+
+
+@mcp.tool()
+def update_agent(
+    agent_id: str,
+    instructions: Optional[List[str]] = None,
+    display_name: Optional[str] = None,
+    is_active: Optional[bool] = None,
+) -> Any:
+    """Update an agent's instructions, display name, or active state."""
+    payload: Dict[str, Any] = {}
+    if instructions is not None:
+        payload["instructions"] = instructions
+    if display_name is not None:
+        payload["display_name"] = display_name
+    if is_active is not None:
+        payload["is_active"] = is_active
+    if not payload:
+        return {"error": "Nothing to update."}
+    client = _client()
+    return _call(lambda: client.update_agent(agent_id, payload))
+
+
+@mcp.tool()
+def create_workflow(agent_id: str, name: str, description: Optional[str] = None) -> Any:
+    """Create a workflow for an agent."""
+    payload: Dict[str, Any] = {"name": name, "agent_id": agent_id}
+    if description is not None:
+        payload["description"] = description
+    client = _client()
+    return _call(lambda: client.create_workflow(payload))
+
+
+@mcp.tool()
+def update_workflow(
+    workflow_id: str,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    status: Optional[str] = None,
+) -> Any:
+    """Update a workflow's metadata. status is draft, published or archived (case-insensitive)."""
+    payload: Dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if description is not None:
+        payload["description"] = description
+    if status is not None:
+        payload["status"] = status.lower()
+    if not payload:
+        return {"error": "Nothing to update."}
+    client = _client()
+    return _call(lambda: client.update_workflow(workflow_id, payload))
+
+
+@mcp.tool()
+def update_workflow_nodes(workflow_id: str, payload: Dict[str, Any]) -> Any:
+    """Replace a workflow's nodes/connections with the given JSON payload."""
+    client = _client()
+    return _call(lambda: client.update_workflow_nodes(workflow_id, payload))
+
+
+@mcp.tool()
+def add_knowledge_url(
+    websites: Optional[List[str]] = None,
+    pdf_urls: Optional[List[str]] = None,
+    agent_id: Optional[str] = None,
+) -> Any:
+    """Add website and/or PDF URLs to the knowledge base, optionally linking to an agent."""
+    if not websites and not pdf_urls:
+        return {"error": "Provide at least one website or pdf_url."}
+    client = _client()
+    org_id = _org_id(client)
+    if not org_id:
+        return {"error": "Could not determine organization for the current credentials."}
+    return _call(lambda: client.add_knowledge(
+        org_id=org_id, pdf_urls=pdf_urls or [], websites=websites or [], agent_id=agent_id,
+    ))
+
+
+@mcp.tool()
+def link_knowledge(knowledge_id: int, agent_id: str) -> Any:
+    """Link a knowledge source to an agent."""
+    client = _client()
+    result = _call(lambda: client.link_knowledge(knowledge_id, agent_id))
+    return result if result is not None else {"ok": True}
+
+
+@mcp.tool()
+def unlink_knowledge(knowledge_id: int, agent_id: str) -> Any:
+    """Unlink a knowledge source from an agent."""
+    client = _client()
+    result = _call(lambda: client.unlink_knowledge(knowledge_id, agent_id))
+    return result if result is not None else {"ok": True}
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

chattermate_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: chattermate-cli
+Version: 0.2.0
+Summary: ChatterMate CLI and MCP server — sign up, authenticate, and configure agents, workflows and knowledge from the terminal or an AI agent.
+Author: ChatterMate
+License: AGPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: mcp>=1.2
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+Dynamic: license-file
+
+# ChatterMate CLI & MCP server
+
+`chattermate-cli` provides a command-line client and an MCP (Model Context Protocol)
+server for ChatterMate. A human can sign up, log in and configure agents, workflows and
+knowledge from the terminal; an AI agent can do the same through the MCP server.
+
+This is an **enterprise** feature and depends on the enterprise backend's Personal Access
+Tokens (PATs).
+
+## Install
+
+```bash
+pip install -e .            # from this directory, for development
+# or, once published:
+pipx install chattermate-cli
+```
+
+Console scripts installed: `chattermate` (alias `cmate`) and `chattermate-mcp`.
+
+## Configure the API endpoint
+
+By default the CLI talks to the hosted API at `https://api.chattermate.chat`. To target a
+local or self-hosted backend, set `CHATTERMATE_API_URL=http://localhost:8000` (or pass
+`--api-url`). Resolution order: `--api-url` flag → `CHATTERMATE_API_URL` env → stored config →
+`https://api.chattermate.chat`.
+
+## Quick start (human)
+
+```bash
+# Create an organization + admin (community signup), or log in to an existing one
+chattermate signup
+chattermate login --email you@acme.com
+
+chattermate whoami
+
+# Mint a long-lived Personal Access Token for CI / AI agents (shown once!)
+chattermate token create laptop-cli
+chattermate token list
+chattermate token revoke <token-id>
+
+# Configure resources
+chattermate agent list
+chattermate agent create --name "Support" --type CUSTOMER_SUPPORT -i "Be concise"
+chattermate workflow get <agent-id>
+chattermate workflow create --agent-id <agent-id> --name "Onboarding"
+chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>
+chattermate knowledge status <queue-id>
+```
+
+Every command accepts `--json` for machine-readable output.
+
+## Authentication
+
+Two credentials are supported:
+
+- **Personal Access Token** (`cmat_...`) — preferred for non-interactive use. Pass it via
+  the `CHATTERMATE_TOKEN` environment variable. Long-lived and revocable.
+- **JWT login** — `chattermate login` stores access + refresh tokens in
+  `~/.chattermate/config.json` (mode `600`) and refreshes automatically.
+
+## MCP server (AI agents)
+
+`chattermate-mcp` is a stdio MCP server. Point your MCP client at it with a PAT:
+
+```json
+{
+  "mcpServers": {
+    "chattermate": {
+      "command": "uvx",
+      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
+      "env": {
+        "CHATTERMATE_TOKEN": "cmat_...",
+        "CHATTERMATE_API_URL": "https://your-chattermate-host"
+      }
+    }
+  }
+}
+```
+
+`chattermate token create` prints a ready-to-paste version of this snippet.
+
+### Tools
+
+Read-only: `whoami`, `list_agents`, `get_agent`, `get_workflow`, `get_workflow_nodes`,
+`list_knowledge`, `get_ingestion_status`.
+
+Mutating: `create_agent`, `update_agent`, `create_workflow`, `update_workflow`,
+`update_workflow_nodes`, `add_knowledge_url`, `link_knowledge`, `unlink_knowledge`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest tests/
+```

chattermate_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+chattermate_cli/__init__.py,sha256=Fl2jq4a5tuyCsxms3gKGE8P9vEGyAXUmw_N7Xqlygw8,724
+chattermate_cli/client.py,sha256=q48K6n9snPqzwcRE958noctenI8y62lhc3q4bJmd29A,10604
+chattermate_cli/config.py,sha256=zagLyijC4HmuwCsEhz45X3Tf5N5PGanc18k0em9SO8I,3360
+chattermate_cli/context.py,sha256=zK27rN9-PH_NTkxbOw1VgTQisLmqw73ppOCgoueykR0,2479
+chattermate_cli/main.py,sha256=JFoRDdPzjGifFgzOxaPleciDnvwWbFwlG3nJ85HDm3g,2107
+chattermate_cli/mcp_server.py,sha256=62m9QQBQAzQCHx5O-vYD8wABwMYfr9I114h68gcRVSU,8051
+chattermate_cli/commands/__init__.py,sha256=I0IyYLYZl-b8dcdVpjaOYQ2lVNYVFov-4eTaCW4jEEQ,700
+chattermate_cli/commands/agent.py,sha256=R81d6XJK0ooAMo4lk15fWgEJSMjZ8LzO4EANTX98gEI,4634
+chattermate_cli/commands/auth.py,sha256=PiNAEM_0IEXa6puF95NxfXA850ZtVX-y6QJFRtIhuw8,7966
+chattermate_cli/commands/knowledge.py,sha256=q10EBzoK0IhqVMQM1swXKHvHr1lxquip9rmpBOs0DdY,4002
+chattermate_cli/commands/workflow.py,sha256=kwyf6Dc8IBFqUC4sQ3lg4WRIifpaW7wcHDMfCpxXTT4,4859
+chattermate_cli-0.2.0.dist-info/licenses/LICENSE,sha256=60gz0wEB0a2wZOoendAWGBrLzAM7jvKAAKdOOm4WEdg,820
+chattermate_cli-0.2.0.dist-info/METADATA,sha256=cqFVk-EV6KD_UgXHhXWDVUSMZocEYR-DkhrMIVQMz40,3520
+chattermate_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+chattermate_cli-0.2.0.dist-info/entry_points.txt,sha256=HYy6P-pExh28Y5vXbJ6PrQTG8iwZZ2oKX-qZWyugXBc,142
+chattermate_cli-0.2.0.dist-info/top_level.txt,sha256=kDj5LfQJr-s1ce222gYWMuQ0kFdxsN241ZmXWdJZw28,16
+chattermate_cli-0.2.0.dist-info/RECORD,,

chattermate_cli-0.2.0.dist-info/WHEEL

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

chattermate_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+chattermate = chattermate_cli.main:main
+chattermate-mcp = chattermate_cli.mcp_server:main
+cmate = chattermate_cli.main:main

chattermate_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+ChatterMate CLI (chattermate-cli)
+Copyright (C) 2024 ChatterMate
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The full text of the GNU Affero General Public License v3.0 is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt

chattermate_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chattermate_cli