Bloom Growth GraphQL Bridge via MCP

An implementation of the Model Context Protocol (MCP) designed specifically to interface with Bloom Growth's underlying GraphQL API infrastructure.

Core Functionality

This server translates standard MCP calls into targeted requests against the Bloom Growth GraphQL service, abstracting the underlying network complexity for AI systems.

• Seamless execution of GraphQL query and mutation operations.
• Automated discovery and reporting of the current GraphQL schema.
• Retrieval of current user identity context.
• Support for structured data retrieval via defined tool endpoints.

Quick Setup Guide

Prerequisites

Ensure you have the following runtime dependencies installed:

• Python interpreter version 3.12 or newer.
• Necessary authorization credentials for the Bloom Growth platform.
• We highly suggest using uv for dependency resolution and installation speed.

Dependency Management (Recommended: uv)

This project utilizes uv due to its superior performance over traditional Python package managers like pip.

To install uv globally:

bash curl -sSf https://astral.sh/uv/install.sh | sh

Consult the official uv documentation for alternative installation paths.

Initialization Steps

1. Clone the source repository locally.

2. Establish an isolated Python environment: bash python -m venv .venv source .venv/bin/activate # Windows users: .venv\Scripts\activate

3. Install the package in editable (development) mode:

   Using pip:

   bash pip install -e .

   Using uv (preferred):

   bash uv pip install -e .

   To include dependencies needed for testing/linting:

   bash uv pip install -e ".[dev]"

Configuration

Configuration requires setting environment variables, typically managed via a .env file placed in the root directory:

BLOOM_API_URL= BLOOM_API_TOKEN=

Integration and Execution

Integrating with Cursor IDE

To configure this server within the Cursor IDE's MCP settings:

1. Navigate to Cursor Settings -> MCP Interfaces.
2. Select the option to 'Add a new MCP service'.

3. Populate the fields as follows:

   • Identifier Name: "Bloom Growth Platform" (or similar short name).
   • Interface Type: Command.
   • Execution Command: uv run --project /path/to/your/repo/ --env-file /path/to/your/repo/.env bloomgy-server

   Crucial: Substitute /path/to/your/repo/ with the absolute file system path to where you cloned this project (e.g., /home/user/projects/bloom-graphql-connector/).

Starting the Service

Launch the connector server process:

bash bloomgy-server

Debugging with the Inspector

For real-time inspection of protocol traffic during development:

bash npx @modelcontextprotocol/inspector bloomgy-server

Development Environment Recommendations

For streamlining workflow and secrets management:

• direnv: Automates loading environment variables when entering the project directory. Install it (e.g., brew install direnv) and create a .envrc file: bash export BLOOM_API_URL=your_api_url export BLOOM_API_TOKEN=your_api_token

  Authorize it with direnv allow. * uv: Ensures fast and consistent dependency resolution.

Combining direnv and uv creates a highly efficient development setup.

Exposed MCP Capabilities

Available Tools (Actions)

• fetch_query_metadata - Retrieves verbose details pertaining to a specific registered GraphQL query.
• fetch_mutation_metadata - Retrieves verbose details pertaining to a specific registered GraphQL mutation.
• run_graphql_operation - Executes either a query or mutation, optionally supplying runtime variables.
• resolve_current_user_identity - Fetches the identifier for the session's authenticated user context.

Available Resources (Data Sources)

• bloom://schema/queries - Provides a comprehensive index of all actionable query definitions.
• bloom://schema/mutations - Provides a comprehensive index of all actionable mutation definitions.

Internal Structure

src/ └── bloomgy_mcp/ ├── init.py # Package entry point ├── client.py # Handles all HTTP/GraphQL communication ├── formatters.py # Utilities for data serialization/presentation ├── introspection.py # Logic for schema discovery ├── operations.py # Core utility functions for executing requests └── server.py # The main MCP server bootstrapping logic

Required Packages

• mcp[cli] - Core MCP framework dependencies.
• gql - Python library for GraphQL interaction.
• httpx - Asynchronous HTTP client used by gql.
• pyyaml - Used for configuration or structured data handling (if applicable).