tooldex 0.1.1__tar.gz

tooldex-0.1.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @RiaBanerjee24

tooldex-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Related issue
+
+<!-- Link any related issue, e.g. Closes #123 -->
+
+## Changes
+
+<!-- Bullet list of the key changes -->
+
+-
+
+## Testing
+
+<!-- How did you verify this works? Include commands run and relevant output. -->
+
+```bash
+
+```
+
+## Checklist
+
+- [ ] I read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] `pytest` passes locally (required — CI will block the merge otherwise)
+- [ ] I added/updated unit tests in `tests/` for any new or changed logic
+- [ ] I manually verified the change (see Testing above)
+- [ ] I updated relevant docs (`README.md`, `README.dev.md`, `docs/index.md`) if behavior changed
+- [ ] This PR is scoped to a single concern

tooldex-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

tooldex-0.1.1/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tooldex with test dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run unit tests
+        run: pytest -v

tooldex-0.1.1/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+build/
+.eggs/
+pip-wheel-metadata/
+.pypirc
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Node
+node_modules/
+tooldex/ui/node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+
+# Test / lint caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Logs
+logs/
+*.log
+audit.log
+changes.txt
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OPA
+*.rego.bak
+
+# Secrets / keys
+*.pem
+*.key
+*.cert
+*.p12
+
+# PyPI / packaging
+*.whl
+*.tar.gz
+MANIFEST

tooldex-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing to Tooldex
+
+Thanks for taking the time to contribute. This guide covers how to set up the project, the expected workflow, and what to include in a pull request.
+
+---
+
+## Contents
+
+- [Getting started](#getting-started)
+- [Development workflow](#development-workflow)
+- [Coding guidelines](#coding-guidelines)
+- [Testing](#testing)
+- [Submitting a pull request](#submitting-a-pull-request)
+- [Reporting bugs](#reporting-bugs)
+- [Adding a new MCP client](#adding-a-new-mcp-client)
+
+---
+
+## Getting started
+
+1. Fork the repository and clone your fork:
+
+   ```bash
+   git clone https://github.com/<your-username>/Tooldex.git
+   cd Tooldex
+   ```
+
+2. Install in editable mode:
+
+   ```bash
+   pip install -e .
+   tooldex --version
+   ```
+
+3. Read [`README.dev.md`](README.dev.md) for an overview of the project structure and architecture before making non-trivial changes.
+
+---
+
+## Development workflow
+
+1. Create a branch off `main`:
+
+   ```bash
+   git checkout -b your-feature-name
+   ```
+
+2. Make your changes. Keep commits focused — one logical change per commit.
+
+3. Run the unit-test suite and add tests for any new behavior (see [Testing](#testing)) before opening a PR. This is mandatory — the same suite runs in CI on every PR and must pass before a PR is considered healthy.
+
+4. Push your branch and open a pull request against `main`.
+
+---
+
+## Coding guidelines
+
+- Match the existing style of the module you're editing rather than introducing a new convention.
+- Keep the sync/async boundary intact: CLI and API handlers are sync; only `core/discovery/mcp_client.py` should contain async I/O. See [`README.dev.md`](README.dev.md#async-architecture).
+- New data structures should be Pydantic v2 models, consistent with `core/models/`.
+- Don't add dependencies unless necessary. If you do, add them to `pyproject.toml` under `dependencies`.
+
+---
+
+## Testing
+
+Tooldex has a `pytest` unit-test suite under `tests/`, covering config parsing, path resolution, discovery merging, manifest building, the parser singleton, and the API routers. **All tests must pass before a PR can be merged** — the same suite runs in CI (see [`.github/workflows/tests.yml`](.github/workflows/tests.yml)) against Python 3.10–3.12.
+
+Install test dependencies and run the suite:
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Run a single file or a single test while iterating:
+
+```bash
+pytest tests/test_parsers.py
+pytest tests/test_parsers.py::TestParseMcpServers::test_parses_stdio_server -v
+```
+
+If you add or change behavior in `tooldex/core/` or `tooldex/api/`, add or update the corresponding test file in `tests/` as part of your PR — a PR that changes logic without matching test coverage will be asked to add it.
+
+For manual, end-to-end checks against your own MCP config:
+
+```bash
+# Verify discovery against your local MCP config
+tooldex run --no-serve
+
+# Inspect the raw discovery payload
+tooldex run --json | jq .
+
+# Confirm the API server starts and responds
+tooldex run
+curl http://127.0.0.1:8282/api/health/
+```
+
+---
+
+## Submitting a pull request
+
+Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) (auto-filled when you open a PR). In summary, include:
+
+- A clear description of what changed and why.
+- Any relevant issue numbers.
+- The manual verification steps you ran (commands + output, where useful).
+- Notes on any follow-up work that's intentionally out of scope.
+
+Keep PRs scoped to a single concern — smaller PRs are easier to review and merge.
+
+---
+
+## Reporting bugs
+
+Open a GitHub issue with:
+
+- Tooldex version (`tooldex --version`)
+- Python version and OS
+- The MCP client(s) and config involved
+- Steps to reproduce, expected behavior, and actual behavior
+- Relevant output from `tooldex run --json` or server logs, with secrets redacted
+
+---
+
+## Adding a new MCP client
+
+See [`README.dev.md` → Adding a new MCP client](README.dev.md#adding-a-new-mcp-client) for the exact steps (path resolvers, `build_plan()` registration, optional status enrichment and agent CLI fallback).

tooldex-0.1.1/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: tooldex
+Version: 0.1.1
+Summary: Unified MCP Server Observatory
+License: MIT
+Keywords: agents,ai,mcp,observability,permissions
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: watchfiles>=0.21.0
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Tooldex
+
+Tooldex autodiscovers MCP servers configured across your AI clients — Claude Code, Cursor, Codex, Docker MCP Toolkit — and surfaces them in a unified UI. No manual config. Run it from any project directory and it finds everything.
+
+---
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How discovery works](#how-discovery-works)
+- [Config file locations](#config-file-locations)
+- [MCP config format](#mcp-config-format)
+- [CLI reference](#cli-reference)
+- [JSON output](#json-output)
+- [API endpoints](#api-endpoints)
+- [Testing](#testing)
+- [Contributing](#contributing)
+
+---
+
+## Requirements
+
+- Python 3.10 or later
+- At least one supported MCP client configured (Claude Code, Cursor, Codex, or Docker MCP Toolkit)
+
+---
+
+## Installation
+
+```bash
+pip install tooldex
+```
+
+Verify:
+
+```bash
+tooldex --version
+```
+
+---
+
+## Quick start
+
+```bash
+cd your-project
+tooldex run
+```
+
+Tooldex scans config files, probes each discovered server for its tool surface, and opens the UI. The startup banner shows where to connect:
+
+```
+  ╔══════════════════════════════════════════════════╗
+  ║         tooldex  v0.1.1                         ║
+  ╠══════════════════════════════════════════════════╣
+  ║  Servers  12                                     ║
+  ║  Tools    187                                    ║
+  ╠══════════════════════════════════════════════════╣
+  ║  →  http://127.0.0.1:8282                        ║
+  ╚══════════════════════════════════════════════════╝
+```
+
+To see the discovery summary without starting the server:
+
+```bash
+tooldex run --no-serve
+```
+
+---
+
+## How discovery works
+
+When you run `tooldex run`, the following happens in order:
+
+1. **Config scan** — Tooldex reads every known MCP config location for the current directory (see [Config file locations](#config-file-locations)). Each found server gets a qualified ID in the form `{client}:{server_name}` so servers from different clients never collide.
+
+2. **Live probe** — Each discovered server is contacted concurrently. Tooldex calls `tools/list` on it and records which tools it exposes, how long it took, and any errors.
+
+3. **Deduplication** — If the same server name appears in multiple clients (e.g., `browserbase` in both Claude Code and Cursor), both are retained as separate entries under their respective clients. Duplicate server names across clients are reported in the `duplicates` field.
+
+4. **UI** — A local web server starts and serves the unified view.
+
+---
+
+## Config file locations
+
+Tooldex checks all of the following on every run. Files that do not exist are skipped silently.
+
+### Claude Code
+
+| Scope | Path |
+|---|---|
+| Global | `~/.claude.json` |
+| Project | `<project>/.claude/mcp.json` |
+| Project (flat) | `<project>/.claude.json` |
+
+### Cursor
+
+| Scope | Path |
+|---|---|
+| Global | `~/.cursor/mcp.json` |
+| Project | `<project>/.cursor/mcp.json` |
+
+### Codex CLI
+
+| Scope | Path |
+|---|---|
+| Global | `~/.codex/config.toml` |
+| Project | `<project>/.codex/config.toml` |
+
+### MCP JSON (shared / team configs)
+
+| Scope | Path |
+|---|---|
+| Global | `~/.mcp.json` |
+| Project | `<project>/.mcp.json` |
+
+### Docker MCP Toolkit
+
+Tooldex reads all Docker MCP profiles via `docker mcp profile ls`. No additional configuration is needed.
+
+**Project-scoped paths** are discovered by walking up the directory tree from `cwd` until the home directory. This means running `tooldex run` from a nested subdirectory will still find a `.mcp.json` at the project root.
+
+---
+
+## MCP config format
+
+All JSON-based clients use the same `mcpServers` structure. Tooldex understands both `stdio` (command-based) and `http`/`sse` (URL-based) transports.
+
+### stdio server (runs a local process)
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
+      "env": {
+        "SOME_VAR": "value"
+      }
+    },
+    "my-db-server": {
+      "command": "node",
+      "args": ["/path/to/my-server/index.js"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "5432"
+      }
+    }
+  }
+}
+```
+
+### HTTP / SSE server (connects to a remote endpoint)
+
+```json
+{
+  "mcpServers": {
+    "browserbase": {
+      "type": "http",
+      "url": "https://mcp.browserbase.com/mcp"
+    },
+    "remote-api": {
+      "type": "sse",
+      "url": "https://api.example.com/mcp/sse"
+    }
+  }
+}
+```
+
+### Codex (`~/.codex/config.toml`)
+
+Codex uses TOML with an `[mcp_servers.<id>]` table per server:
+
+```toml
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+[mcp_servers.github]
+type = "http"
+url = "https://api.githubcopilot.com/mcp/"
+```
+
+### What Tooldex detects from these files
+
+For each config file found, Tooldex reports:
+
+- **`status`** — `found` / `not_found` / `empty` / `parse_error` / `read_error`
+- **`server_ids`** — list of server names parsed from the file
+- **`in_file_duplicates`** — server names that appeared more than once as JSON keys (the last value is kept; all prior definitions are silently dropped by the JSON parser)
+
+For each server probed:
+
+- **`status`** — `found` / `timeout` / `connection_failed` / `protocol_error` / `missing_command`
+- **`tools`** — names, descriptions, and input schemas of every tool the server exposes
+- **`duration_ms`** — probe wall time
+- **`error`** — human-readable failure message when status is not `found`; includes install hints for common missing runtimes (`uvx`, `npx`, `docker`, etc.)
+
+---
+
+## CLI reference
+
+```
+tooldex [OPTIONS] COMMAND [ARGS]
+```
+
+### Global options
+
+| Flag | Description |
+|---|---|
+| `--version`, `-V` | Print version and exit |
+| `--help`, `-h` | Show help |
+
+### `tooldex run`
+
+Autodiscover MCP servers and start the UI.
+
+```bash
+tooldex run [OPTIONS]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--port`, `-p` | `8282` | Starting port. Increments automatically if occupied. |
+| `--host` | `127.0.0.1` | Interface to bind the UI server to. |
+| `--no-serve` | off | Print discovery summary and exit without starting the server. |
+| `--json` | off | Print discovery result as JSON and exit. Implies `--no-serve`. Does not probe servers. |
+| `--timeout` | `10.0` | Per-server probe timeout in seconds. |
+| `--concurrency` | `8` | Maximum concurrent server probes. |
+| `--no-probe <name>` | — | Skip probing a specific server by name. Repeatable. |
+| `--config <path>` | — | Additional MCP config file to include. Repeatable. Custom configs are processed first and win on duplicate server IDs. |
+
+All flags accept both `--flag` and `-flag` prefix.
+
+#### Examples
+
+```bash
+# Discover and launch UI
+tooldex run
+
+# Custom port and host
+tooldex run --port 9000 --host 0.0.0.0
+
+# Just print what was found, don't start the server
+tooldex run --no-serve
+
+# Skip slow or broken servers during probing
+tooldex run --no-probe node-api-docs --no-probe local-mcp
+
+# Include an extra config file
+tooldex run --config ~/shared/team-servers.json
+
+# Increase timeout for slow servers
+tooldex run --timeout 30
+
+# Use all 16 cores for probing
+tooldex run --concurrency 16
+
+# Pipe the discovery result into jq
+tooldex run --json | jq '.duplicates'
+```
+
+---
+
+## JSON output
+
+`tooldex run --json` prints a single JSON object to stdout and exits. No servers are probed; this is fast and side-effect-free for use in scripts and CI.
+
+```json
+{
+  "sources": [
+    {
+      "client": "claude_code_user",
+      "path": "/home/user/.claude.json",
+      "status": "found",
+      "error": null,
+      "server_ids": ["filesystem", "github"],
+      "in_file_duplicates": []
+    },
+    {
+      "client": "mcp_json_user",
+      "path": "/home/user/.mcp.json",
+      "status": "not_found",
+      "error": null,
+      "server_ids": [],
+      "in_file_duplicates": []
+    }
+  ],
+  "servers": {
+    "claude_code_user:filesystem": {
+      "name": "filesystem",
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
+      "url": null
+    }
+  },
+  "duplicates": [
+    "\"filesystem\" in cursor_user is also configured in claude_code_user",
+    "\"firecrawl-mcp\" is a duplicate key in /home/user/.mcp.json (last value kept)"
+  ]
+}
+```
+
+**Fields:**
+
+| Field | Description |
+|---|---|
+| `sources` | Every config location checked, with status and server IDs found. |
+| `servers` | Deduplicated map of all servers, keyed by `{client}:{server_id}`. |
+| `duplicates` | Human-readable notes about server name collisions across clients, and duplicate JSON keys within a single file. |
+
+**Exit codes:** `0` on success, `1` on serialisation error.
+
+---
+
+## API endpoints
+
+When the server is running (default `http://127.0.0.1:8282`):
+
+All endpoints respond with or without a trailing slash.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/health/` | `status`, current `timestamp`, and `uptime_seconds` since the server started |
+| `GET` | `/api/servers/` | All MCP servers with `total_servers`, `total_tools`, `scanned_at`. Per server: `tool_count`, `source_file` |
+| `GET` | `/api/servers/{id}/` | Single server with full tool detail |
+| `POST` | `/api/servers/{id}/rescan/` | Re-probe a single server and update its tools in place |
+| `GET` | `/api/files/` | All config files that were scanned: path, client, status, server IDs found, any parse errors |
+| `POST` | `/api/rescan/` | Full rediscovery — re-reads all MCP configs and re-probes every server. Returns `{"status": "already_scanning"}` if a rescan is already in progress. |
+
+---
+
+## Testing
+
+Tooldex has a `pytest` unit-test suite that runs in CI on every PR:
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#testing) for details. For ad-hoc manual checks against your own MCP config:
+
+```bash
+# Verify discovery against your local config
+tooldex run --no-serve
+
+# Inspect the raw discovery payload
+tooldex run --json | jq .
+
+# Check a specific extra config file
+tooldex run --config ./my-config.json --json
+
+# Confirm a server is reachable with a longer timeout
+tooldex run --timeout 30 --no-probe github
+```
+
+To run the package from source without installing:
+
+```bash
+git clone <repo>
+cd Tooldex
+pip install -e .
+tooldex --version
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, the development workflow, and pull request guidelines.