{"id":38559373,"url":"https://github.com/knuckles-team/documentdb-mcp","last_synced_at":"2026-04-02T13:14:52.904Z","repository":{"id":328758852,"uuid":"1115815048","full_name":"Knuckles-Team/documentdb-mcp","owner":"Knuckles-Team","description":"DocumentDB A2A + MCP Server ","archived":false,"fork":false,"pushed_at":"2026-02-27T08:44:31.000Z","size":275,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-27T10:38:08.588Z","etag":null,"topics":["a2a","a2a-server","ag-ui","documentdb","mcp-server","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Knuckles-Team.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-12-13T15:59:02.000Z","updated_at":"2026-02-27T08:35:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Knuckles-Team/documentdb-mcp","commit_stats":null,"previous_names":["knuckles-team/documentdb-mcp"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/Knuckles-Team/documentdb-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knuckles-Team%2Fdocumentdb-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knuckles-Team%2Fdocumentdb-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knuckles-Team%2Fdocumentdb-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knuckles-Team%2Fdocumentdb-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Knuckles-Team","download_url":"https://codeload.github.com/Knuckles-Team/documentdb-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Knuckles-Team%2Fdocumentdb-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"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":["a2a","a2a-server","ag-ui","documentdb","mcp-server","python"],"created_at":"2026-01-17T07:46:19.225Z","updated_at":"2026-04-02T13:14:52.897Z","avatar_url":"https://github.com/Knuckles-Team.png","language":"Python","readme":"# DocumentDB - A2A | AG-UI | MCP\n\n![PyPI - Version](https://img.shields.io/pypi/v/documentdb-mcp)\n![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')\n![PyPI - Downloads](https://img.shields.io/pypi/dd/documentdb-mcp)\n![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/documentdb-mcp)\n![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/documentdb-mcp)\n![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/documentdb-mcp)\n![PyPI - License](https://img.shields.io/pypi/l/documentdb-mcp)\n![GitHub](https://img.shields.io/github/license/Knuckles-Team/documentdb-mcp)\n\n![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/documentdb-mcp)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/documentdb-mcp)\n![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/documentdb-mcp)\n![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/documentdb-mcp)\n\n![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/documentdb-mcp)\n![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/documentdb-mcp)\n![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/documentdb-mcp)\n![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/documentdb-mcp)\n![PyPI - Wheel](https://img.shields.io/pypi/wheel/documentdb-mcp)\n![PyPI - Implementation](https://img.shields.io/pypi/implementation/documentdb-mcp)\n\n*Version: 0.1.47*\n\n## Overview\n\nDocumentDB + MCP Server + A2A\n\nA [FastMCP](https://github.com/jlowin/fastmcp) server and A2A (Agent-to-Agent) agent for [DocumentDB](https://documentdb.io/).\nDocumentDB is a MongoDB-compatible open source document database built on PostgreSQL.\n\nThis package provides:\n1.  **MCP Server**: Exposes DocumentDB functionality (CRUD, Administration) as tools for LLMs.\n2.  **A2A Agent**: A specialized agent that uses these tools to help users manage their database.\n\n### Features\n\n-   **CRUD Operations**: Insert, Find, Update, Replace, Delete, Count, Distinct, Aggregate.\n-   **Collection Management**: Create, Drop, List, Rename collections.\n-   **User Management**: Create, Update, Drop users.\n-   **Direct Commands**: Run raw database commands.\n\n\n## MCP\n\n### MCP Tools\n\n| Function Name          | Description                                                                                     | Tag(s)        |\n|:-----------------------|:------------------------------------------------------------------------------------------------|:--------------|\n| `binary_version`       | Get the binary version of the server (using buildInfo).                                         | `system`      |\n| `list_databases`       | List all databases in the connected DocumentDB/MongoDB instance.                                | `system`      |\n| `run_command`          | Run a raw command against the database.                                                         | `system`      |\n| `list_collections`     | List all collections in a specific database.                                                    | `collections` |\n| `create_collection`    | Create a new collection in the specified database.                                              | `collections` |\n| `drop_collection`      | Drop a collection from the specified database.                                                  | `collections` |\n| `create_database`      | Explicitly create a database by creating a collection in it (MongoDB creates DBs lazily).       | `collections` |\n| `drop_database`        | Drop a database.                                                                                | `collections` |\n| `rename_collection`    | Rename a collection.                                                                            | `collections` |\n| `create_user`          | Create a new user on the specified database.                                                    | `users`       |\n| `drop_user`            | Drop a user from the specified database.                                                        | `users`       |\n| `update_user`          | Update a user's password or roles.                                                              | `users`       |\n| `users_info`           | Get information about a user.                                                                   | `users`       |\n| `insert_one`           | Insert a single document into a collection.                                                     | `crud`        |\n| `insert_many`          | Insert multiple documents into a collection.                                                    | `crud`        |\n| `find_one`             | Find a single document matching the filter.                                                     | `crud`        |\n| `find`                 | Find documents matching the filter.                                                             | `crud`        |\n| `replace_one`          | Replace a single document matching the filter.                                                  | `crud`        |\n| `update_one`           | Update a single document matching the filter. 'update' must contain update operators like $set. | `crud`        |\n| `update_many`          | Update multiple documents matching the filter.                                                  | `crud`        |\n| `delete_one`           | Delete a single document matching the filter.                                                   | `crud`        |\n| `delete_many`          | Delete multiple documents matching the filter.                                                  | `crud`        |\n| `count_documents`      | Count documents matching the filter.                                                            | `crud`        |\n| `distinct`             | Find distinct values for a key.                                                                 | `analysis`    |\n| `aggregate`            | Run an aggregation pipeline.                                                                    | `analysis`    |\n| `find_one_and_update`  | Finds a single document and updates it. return_document: 'before' or 'after'.                   | `crud`        |\n| `find_one_and_replace` | Finds a single document and replaces it. return_document: 'before' or 'after'.                  | `crud`        |\n| `find_one_and_delete`  | Finds a single document and deletes it.                                                         | `crud`        |\n\n## A2A Agent\n\n### Architecture:\n\n```mermaid\n---\nconfig:\n  layout: dagre\n---\nflowchart TB\n subgraph subGraph0[\"Agent Capabilities\"]\n        C[\"Agent\"]\n        B[\"A2A Server - Uvicorn/FastAPI\"]\n        D[\"MCP Tools\"]\n        F[\"Agent Skills\"]\n  end\n    C --\u003e D \u0026 F\n    A[\"User Query\"] --\u003e B\n    B --\u003e C\n    D --\u003e E[\"Platform API\"]\n\n     C:::agent\n     B:::server\n     A:::server\n    classDef server fill:#f9f,stroke:#333\n    classDef agent fill:#bbf,stroke:#333,stroke-width:2px\n    style B stroke:#000000,fill:#FFD600\n    style D stroke:#000000,fill:#BBDEFB\n    style F fill:#BBDEFB\n    style A fill:#C8E6C9\n    style subGraph0 fill:#FFF9C4\n```\n\n### Component Interaction Diagram\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Server as A2A Server\n    participant Agent as Agent\n    participant Skill as Agent Skills\n    participant MCP as MCP Tools\n\n    User-\u003e\u003eServer: Send Query\n    Server-\u003e\u003eAgent: Invoke Agent\n    Agent-\u003e\u003eSkill: Analyze Skills Available\n    Skill-\u003e\u003eAgent: Provide Guidance on Next Steps\n    Agent-\u003e\u003eMCP: Invoke Tool\n    MCP--\u003e\u003eAgent: Tool Response Returned\n    Agent--\u003e\u003eAgent: Return Results Summarized\n    Agent--\u003e\u003eServer: Final Response\n    Server--\u003e\u003eUser: Output\n```\n\n## Usage\n\n### MCP CLI\n\n| Short Flag | Long Flag                       | Description                                                                                               |\n|------------|---------------------------------|-----------------------------------------------------------------------------------------------------------|\n| -h         | --help                          | Display help information                                                                                  |\n| -t         | --transport                     | Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio)                                     |\n| -s         | --host                          | Host address for HTTP transport (default: 0.0.0.0)                                                        |\n| -p         | --port                          | Port number for HTTP transport (default: 8000)                                                            |\n|            | --auth-type                     | Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none) |\n|            | --token-jwks-uri                | JWKS URI for JWT verification                                                                             |\n|            | --token-issuer                  | Issuer for JWT verification                                                                               |\n|            | --token-audience                | Audience for JWT verification                                                                             |\n|            | --token-algorithm               | JWT signing algorithm (e.g., HS256, RS256). Required for HMAC or static keys. Auto-detected for JWKS.     |\n|            | --token-secret                  | Shared secret for HMAC (HS*) verification. Used with --token-algorithm.                                   |\n|            | --token-public-key              | Path to PEM public key file or inline PEM string for static asymmetric verification.                      |\n|            | --required-scopes               | Comma-separated required scopes (e.g., documentdb.read,documentdb.write). Enforced by JWTVerifier.        |\n|            | --oauth-upstream-auth-endpoint  | Upstream authorization endpoint for OAuth Proxy                                                           |\n|            | --oauth-upstream-token-endpoint | Upstream token endpoint for OAuth Proxy                                                                   |\n|            | --oauth-upstream-client-id      | Upstream client ID for OAuth Proxy                                                                        |\n|            | --oauth-upstream-client-secret  | Upstream client secret for OAuth Proxy                                                                    |\n|            | --oauth-base-url                | Base URL for OAuth Proxy                                                                                  |\n|            | --oidc-config-url               | OIDC configuration URL                                                                                    |\n|            | --oidc-client-id                | OIDC client ID                                                                                            |\n|            | --oidc-client-secret            | OIDC client secret                                                                                        |\n|            | --oidc-base-url                 | Base URL for OIDC Proxy                                                                                   |\n|            | --remote-auth-servers           | Comma-separated list of authorization servers for Remote OAuth                                            |\n|            | --remote-base-url               | Base URL for Remote OAuth                                                                                 |\n|            | --allowed-client-redirect-uris  | Comma-separated list of allowed client redirect URIs                                                      |\n|            | --eunomia-type                  | Eunomia authorization type: 'none', 'embedded', 'remote' (default: none)                                  |\n|            | --eunomia-policy-file           | Policy file for embedded Eunomia (default: mcp_policies.json)                                             |\n|            | --eunomia-remote-url            | URL for remote Eunomia server                                                                             |\n|            | --enable-delegation             | Enable OIDC token delegation to (default: False)                                                          |\n|            | --audience                      | Audience for the delegated token                                                                          |\n|            | --delegated-scopes              | Scopes for the delegated token (space-separated)                                                          |\n|            | --openapi-file                  | Path to OpenAPI JSON spec to import tools/resources from                                                  |\n|            | --openapi-base-url              | Base URL for the OpenAPI client (defaults to instance URL)                                                |\n\n\n### A2A CLI\n#### Endpoints\n- **Web UI**: `http://localhost:8000/` (if enabled)\n- **A2A**: `http://localhost:8000/a2a` (Discovery: `/a2a/.well-known/agent.json`)\n- **AG-UI**: `http://localhost:8000/ag-ui` (POST)\n\n| Short Flag | Long Flag         | Description                                                            |\n|------------|-------------------|------------------------------------------------------------------------|\n| -h         | --help            | Display help information                                               |\n|            | --host            | Host to bind the server to (default: 0.0.0.0)                          |\n|            | --port            | Port to bind the server to (default: 9000)                             |\n|            | --reload          | Enable auto-reload                                                     |\n|            | --provider        | LLM Provider: 'openai', 'anthropic', 'google', 'huggingface'           |\n|            | --model-id        | LLM Model ID (default: nvidia/nemotron-3-super)                                  |\n|            | --base-url        | LLM Base URL (for OpenAI compatible providers)                         |\n|            | --api-key         | LLM API Key                                                            |\n|            | --mcp-url         | MCP Server URL (default: http://localhost:8000/mcp)                    |\n|            | --web             | Enable Pydantic AI Web UI                                              | False (Env: ENABLE_WEB_UI) |\n\n## Usage\n\n### 1. DocumentDB MCP Server\n\nThe MCP server connects to your DocumentDB (or MongoDB) instance.\n\n**Environment Variables:**\n\n-   `MONGODB_URI`: Connection string (e.g., `mongodb://localhost:27017/`).\n-   Alternatively: `MONGODB_HOST` (default: `localhost`) and `MONGODB_PORT` (default: `27017`).\n\n**Running the Server:**\n\n```bash\n# Stdio mode (default)\ndocumentdb-mcp\n\n# HTTP mode\ndocumentdb-mcp --transport http --port 8000\n```\n\n### 2. DocumentDB A2A Agent\n\nThe A2A agent connects to the MCP server to perform tasks.\n\n**Environment Variables:**\n\n-   `LLM_API_KEY` / `LLM_API_KEY`: API key for your chosen LLM provider.\n-   `LLM_BASE_URL`: (Optional) Base URL for OpenAI-compatible providers (e.g. Ollama).\n\n**Running the Agent:**\n\n```bash\n# Start Agent Server (Default: OpenAI/Ollama)\ndocumentdb-agent\n\n# Custom Configuration\ndocumentdb-agent --provider anthropic --model-id claude-3-5-sonnet-20240620 --mcp-url http://localhost:8000/mcp\n```\n\n\n## Graph Architecture\n\nThis agent uses `pydantic-graph` orchestration for intelligent routing and optimal context management.\n\n```mermaid\n---\ntitle: Documentdb MCP Graph Agent\n---\nstateDiagram-v2\n  [*] --\u003e RouterNode: User Query\n  RouterNode --\u003e DomainNode: Classified Domain\n  RouterNode --\u003e [*]: Low confidence / Error\n  DomainNode --\u003e [*]: Domain Result\n```\n\n- **RouterNode**: A fast, lightweight LLM (e.g., `gpt-4o-mini`) that classifies the user's query into one of the specialized domains.\n- **DomainNode**: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., `gpt-4o`) to complete the request. This preserves LLM context and prevents tool hallucination.\n\n## Installation\n\n```bash\npip install documentdb-mcp\n```\n\n## Development\n\n```bash\n# Install dependencies\npip install -e \".[dev]\"\n\n# Run tests or verification\npython -m build\n```\n\n## Repository Owners\n\n\u003cimg width=\"100%\" height=\"180em\" src=\"https://github-readme-stats.vercel.app/api?username=Knucklessg1\u0026show_icons=true\u0026hide_border=true\u0026\u0026count_private=true\u0026include_all_commits=true\"  alt=\"\"/\u003e\n\n![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)\n\n![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknuckles-team%2Fdocumentdb-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknuckles-team%2Fdocumentdb-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknuckles-team%2Fdocumentdb-mcp/lists"}