{
  "markdown": "# unblu-mcp\n\n<!-- mcp-name: io.github.detailobsessed/unblu -->\n\n[![ci](https://github.com/detailobsessed/unblu-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/detailobsessed/unblu-mcp/actions/workflows/ci.yml)\n[![documentation](https://img.shields.io/badge/docs-zensical-708FCC.svg?style=flat)](https://detailobsessed.github.io/unblu-mcp/)\n[![pypi version](https://img.shields.io/pypi/v/unblu-mcp.svg)](https://pypi.org/project/unblu-mcp/)\n[![python versions](https://img.shields.io/pypi/pyversions/unblu-mcp.svg)](https://pypi.org/project/unblu-mcp/)\n[![license](https://img.shields.io/pypi/l/unblu-mcp.svg)](https://github.com/detailobsessed/unblu-mcp/blob/main/LICENSE)\n[![FastMCP](https://img.shields.io/badge/FastMCP-3.1+-00ADD8.svg)](https://github.com/jlowin/fastmcp)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for debugging and operating [Unblu](https://www.unblu.com/) deployments. Optimised for debugging workflows — curated typed tools for common operations, plus an escape hatch for the full 300+ endpoint API.\n\n**📚 [Full Documentation](https://detailobsessed.github.io/unblu-mcp/)**\n\n## Design\n\nThe server exposes three layers, each progressively more powerful:\n\n| Layer | What it is | When to use |\n|-------|-----------|-------------|\n| **Curated tools** | Typed, token-efficient tools for common debugging tasks | 90% of debugging sessions |\n| **`execute_operation`** | Generic escape hatch for any of 331 Unblu API operations | When a curated tool doesn't exist |\n| **Resources** | Read-only `api://` URIs for browsing the API surface | Discovery and schema inspection |\n\n## Quick Start\n\n### Installation\n\n```bash\nuvx unblu-mcp\n```\n\nOr install persistently: `uv tool install unblu-mcp`\n\n### MCP Client Configuration\n\nDirect API access with an API key:\n\n```json\n{\n  \"mcpServers\": {\n    \"unblu\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unblu-mcp\"],\n      \"env\": {\n        \"UNBLU_BASE_URL\": \"https://your-instance.unblu.cloud/app/rest/v4\",\n        \"UNBLU_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nKubernetes port-forward (auto-managed):\n\nFor `--provider k8s`, you need all of the following:\n\n- `kubectl` installed and available to the MCP client process\n- a valid Kubernetes login with access to the target namespace\n- a K8s environment map in `~/.unblu-mcp/k8s_environments.yaml` or passed with `--k8s-config`\n\nQuick bootstrap:\n\n```bash\nmkdir -p ~/.unblu-mcp\nuvx unblu-mcp --print-k8s-config-template > ~/.unblu-mcp/k8s_environments.yaml\n```\n\nThe `--environment` value must match a key from that YAML file, such as `dev`, `test1`, or `t1`.\n\nMinimal config file:\n\n```yaml\nenvironments:\n  dev:\n    local_port: 8084\n    namespace: unblu-dev\n    service: haproxy\n    service_port: 8080\n    api_path: /app/rest/v4\n```\n\nThen point your MCP client at that environment:\n\n```json\n{\n  \"mcpServers\": {\n    \"unblu\": {\n      \"command\": \"uvx\",\n      \"args\": [\"unblu-mcp\", \"--provider\", \"k8s\", \"--environment\", \"dev\"],\n      \"env\": {\n        \"PATH\": \"/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\nThe `env` block is optional if your MCP client already inherits a `PATH` that includes both `uvx` and `kubectl`. Keep it if the client cannot otherwise find those binaries.\n\n## Tools\n\n### Curated tools (read-only)\n\n| Tool | Description |\n|------|-------------|\n| `get_current_account` | Current account info — good first call to verify connectivity |\n| `search_conversations(status?, topic?, assignee_id?, limit?, fields?)` | Search conversations with filters |\n| `get_conversation(conversation_id)` | Full conversation detail with participants |\n| `search_persons(query?, email?, limit?, fields?)` | Find persons (visitors, agents) |\n| `get_person(person_id)` | Full person detail |\n| `get_persons(identifiers, fields?)` | Batch-resolve up to 20 persons in parallel |\n| `search_users(query?, email?, limit?, fields?)` | Find registered users |\n| `get_user(user_id)` | Full user detail |\n| `check_agent_availability(named_area_id?)` | Check agent availability per named area |\n| `search_named_areas(query?, limit?)` | List named areas (routing targets) |\n| `find_operation(query, service?, include_schema?, limit?)` | Discover API operations by keyword |\n\n### Mutation tools\n\n| Tool | Description |\n|------|-------------|\n| `assign_conversation(conversation_id, agent_id)` | Assign a conversation to an agent |\n| `end_conversation(conversation_id)` | End an active conversation |\n\n### Escape hatch\n\n| Tool | Description |\n|------|-------------|\n| `execute_operation(operation_id, path_params?, query_params?, body?, fields?, confirm_destructive?)` | Execute any of the 331 Unblu API operations |\n\n### Resources\n\n| URI | Description |\n|-----|-------------|\n| `api://services` | JSON list of all API service groups |\n| `api://operations/{operation_id}` | Full resolved schema for a specific operation |\n\n### Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `debug_conversation(conversation_id)` | Step-by-step debugging workflow for a conversation |\n| `find_agent(criteria)` | Locate an agent and check their availability |\n| `account_health_check` | Validate account configuration and connectivity |\n\n## Development\n\n```bash\ngit clone https://github.com/detailobsessed/unblu-mcp.git\ncd unblu-mcp\nuv sync --all-extras --dev\nuv run poe test\n```\n\n## License\n\nISC License\n",
  "bytes": 5389,
  "sha": "8b89c59d593d7422dd2997ea5748eb68625e5f04f02bbadd4cfbc3e178cc0633",
  "repo_slug": "detailobsessed/unblu-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_detailobsessed_unblu_12dd0932/readme"
}