{"id":50506402,"url":"https://github.com/computerlovetech/agent-diagnostics-mcp","last_synced_at":"2026-06-02T16:30:39.811Z","repository":{"id":359424584,"uuid":"1243225103","full_name":"computerlovetech/agent-diagnostics-mcp","owner":"computerlovetech","description":"A simple Agent Self-diagnostics MCP Server - Used for educational purposes","archived":false,"fork":false,"pushed_at":"2026-05-21T20:01:18.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T05:26:25.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/computerlovetech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T06:44:26.000Z","updated_at":"2026-05-21T20:01:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/computerlovetech/agent-diagnostics-mcp","commit_stats":null,"previous_names":["computerlovetech/agent-diagnostics-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/computerlovetech/agent-diagnostics-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/computerlovetech%2Fagent-diagnostics-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/computerlovetech%2Fagent-diagnostics-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/computerlovetech%2Fagent-diagnostics-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/computerlovetech%2Fagent-diagnostics-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/computerlovetech","download_url":"https://codeload.github.com/computerlovetech/agent-diagnostics-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/computerlovetech%2Fagent-diagnostics-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33831622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T16:30:39.000Z","updated_at":"2026-06-02T16:30:39.805Z","avatar_url":"https://github.com/computerlovetech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Diagnostics MCP\n\nAn MCP server that lets agents self-report genuine failures — missing context, broken tools, capability gaps, loops, and bad tool selection. Reports persist in SQLite and can be inspected through a FastAPI web UI.\n\n## Setup\n\nRequires Python 3.11 or newer.\n\nClone the GitHub repository:\n\n```bash\ngit clone https://github.com/computerlovetech/agent-diagnostics-mcp.git\ncd agent-diagnostics-mcp\n```\n\nInstall dependencies for local development with uv:\n\n```bash\nuv sync --group dev\n```\n\nOr install the package into a virtual environment with pip:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e .\n```\n\n## Run the web UI and MCP server\n\n```bash\nuv run agent-diagnostics run\n```\n\nFor development reloads:\n\n```bash\nuv run agent-diagnostics run --reload\n```\n\nBy default this binds `127.0.0.1:8765` and fails if the port is already in use. Use\n`--host` or `--port` to override it:\n\n```bash\nuv run agent-diagnostics run --host 127.0.0.1 --port 9000\n```\n\nOr with uvicorn directly:\n\n```bash\nuv run uvicorn agent_diagnostics_mcp.web_app:app --host 127.0.0.1 --port 8765 --reload\n```\n\nThen open `http://localhost:8765`.\n\nThe MCP HTTP endpoint is available at `http://localhost:8765/mcp/`.\n\n## Run only the MCP server\n\n```bash\nuv run python -m agent_diagnostics_mcp.mcp_server\n```\n\nThis standalone MCP-only entrypoint starts the MCP HTTP transport at\n`http://127.0.0.1:8011/mcp`. The `agent-diagnostics install` command does **not** target this\nstandalone port by default; it targets the combined web UI + MCP server at\n`http://localhost:8765/mcp/`.\n\n## MCP client configuration\n\nStart the combined server first (`agent-diagnostics run`), then use the CLI to register the MCP\nendpoint and failure-reporting hooks in your client's settings files.\n\n### `agent-diagnostics install`\n\nAdds or updates an `agent-diagnostics` MCP server entry and installs the matching\nfailure-reporting hook for one client.\n\n```bash\n# uv\nuv run agent-diagnostics install cursor\nuv run agent-diagnostics install claude-code\nuv run agent-diagnostics install codex\nuv run agent-diagnostics install copilot\n\n# pip (after activating your venv)\nagent-diagnostics install cursor\n```\n\n**Clients:** `cursor`, `claude-code`, `codex`, `copilot`. `claude` is an alias for `claude-code`.\n\n**Options:**\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `CLIENT` | (required) | MCP client to configure |\n| `--url` | `http://localhost:8765/mcp/` | MCP endpoint URL |\n| `--name` | `agent-diagnostics` | Server name in the settings file |\n| `--settings-file` | Client default (see below) | Path to a custom MCP settings file |\n| `--hooks-url` | `http://localhost:8765/api/tool-call-failures` | Hook target URL |\n| `--hooks-settings-file` | Client default (see below) | Path to a custom hooks settings file |\n\nExample with a non-default URL or project-local settings:\n\n```bash\nuv run agent-diagnostics install cursor \\\n  --url http://127.0.0.1:9000/mcp/ \\\n  --hooks-url http://127.0.0.1:9000/api/tool-call-failures\nuv run agent-diagnostics install cursor \\\n  --settings-file .cursor/mcp.json \\\n  --hooks-settings-file .cursor/hooks.json\n```\n\nOn success, the command prints which MCP and hook files were updated and which URLs were\nwritten.\n\n### `agent-diagnostics uninstall`\n\nRemoves the `agent-diagnostics` MCP server entry and installed hooks from **all** supported\nclients (Cursor, Claude Code, Codex, and Copilot) in one run.\n\n```bash\n# uv\nuv run agent-diagnostics uninstall\n\n# pip\nagent-diagnostics uninstall\n```\n\n**Options:**\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `--name` | `agent-diagnostics` | Server name to remove |\n\nThe command reports whether an MCP entry was removed or was already absent for each client,\nand reports hook removals when hooks were present.\n\n### Settings files\n\n| Client | Default settings file |\n| --- | --- |\n| Cursor | `~/.cursor/mcp.json` |\n| Claude Code | `~/.claude.json` |\n| Codex | `~/.codex/config.toml` |\n| Copilot | `~/.copilot/mcp-config.json` |\n\n### Cursor\n\nThe Cursor installer writes to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-diagnostics\": {\n      \"url\": \"http://localhost:8765/mcp/\"\n    }\n  }\n}\n```\n\n### Claude Code\n\nThe Claude Code installer writes to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-diagnostics\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8765/mcp/\"\n    }\n  }\n}\n```\n\nClaude Code also accepts `\"type\": \"streamable-http\"` as an alias for `\"http\"`.\n\n### Codex\n\nThe Codex installer writes to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.agent-diagnostics]\nurl = \"http://localhost:8765/mcp/\"\n```\n\nVerify with `codex mcp list` or `/mcp` in the Codex TUI.\n\n### Copilot\n\nThe Copilot installer writes to `~/.copilot/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-diagnostics\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8765/mcp/\",\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\nVerify with `/mcp show` in Copilot CLI.\n\n## Hook installation\n\nHooks forward failed tool calls from your agent harness to the diagnostics server. Start the\nserver first (`agent-diagnostics run`), then install for your client.\n\n```bash\nuv run agent-diagnostics install cursor\nuv run agent-diagnostics install claude-code\nuv run agent-diagnostics install codex\nuv run agent-diagnostics install copilot\n```\n\n`install` writes both the MCP server entry and a failure-reporting hook for the chosen client.\nUse `--hooks-url` or `--hooks-settings-file` to override the hook defaults.\n\n### Hooks settings files\n\n| Client | Default hooks file | Hook event |\n| --- | --- | --- |\n| Cursor | `~/.cursor/hooks.json` | `postToolUseFailure` |\n| Claude Code | `~/.claude/settings.json` | `PostToolUseFailure` |\n| Codex | `~/.codex/hooks.json` | `PostToolUse` (with runner-side failure detection) |\n| Copilot | `~/.copilot/hooks/agent-diagnostics.json` | `postToolUseFailure` |\n\nClaude Code uses a native HTTP hook that POSTs directly to the API. Cursor, Codex, and Copilot install a\nstandalone Python script next to the hooks settings file (for example `~/.cursor/hooks/agent-diagnostics-tool-call-failure.py`\nor `.cursor/hooks/agent-diagnostics-tool-call-failure.py` in a project). The script only needs\nthe Python standard library and does not require this package to be installed. Codex fires\n`PostToolUse` for all tool completions, so the script filters out successful calls before\nreporting.\n\nFor project hooks, pass `--hooks-settings-file .cursor/hooks.json` so the script is written under\n`.cursor/hooks/` and referenced as `.cursor/hooks/agent-diagnostics-tool-call-failure.py`.\n\n`agent-diagnostics uninstall` removes both MCP entries and hooks from all providers.\n\n## Storage\n\nReports are stored in `~/.agent-diagnostics/diagnostics.sqlite3` by default. The mounted MCP endpoint and the web UI share the same repository instance.\n\n## Tests\n\n```bash\nuv run pytest\nuv run ruff check src tests\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomputerlovetech%2Fagent-diagnostics-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomputerlovetech%2Fagent-diagnostics-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomputerlovetech%2Fagent-diagnostics-mcp/lists"}