Bloom Growth Platform Connector via MCP

This repository details the implementation of a Model Context Protocol (MCP) server specifically engineered to interface seamlessly with the Bloom Growth GraphQL API ecosystem.

Core Functionality

This component acts as a proxy, translating high-level MCP requests into precise GraphQL operations against the Bloom Growth backend, allowing AI agents to manipulate and inspect platform data.

Capabilities Summary

• GraphQL Execution: Dispatching complex queries and data-modifying mutations to the Bloom Growth endpoint.
• Contextual Data Retrieval: Fetching authenticated user credentials and associated metadata.
• Self-Documentation: Performing real-time introspection on the available GraphQL schema elements.

Deployment and Setup Guide

System Prerequisites

To successfully run this service, ensure your environment meets the following minimum specifications:

1. Python Runtime: Version 3.12 or newer is mandatory.
2. API Access: Valid credentials and endpoint authorization for the Bloom Growth service.
3. Dependency Manager: The uv tool (recommended, see below) or standard pip.

Package Management Recommendation (Using uv)

We strongly advocate for utilizing uv, a next-generation Python package installer known for its exceptional speed over legacy tools like pip.

Installing uv:

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

Refer to the official uv documentation for alternative installation routes.

Initial Configuration

1. Obtain a local copy of the source code repository.

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

3. Install dependencies in editable mode:

   Using uv (Preferred Method): bash uv pip install -e . uv pip install -e ".[dev]" # For development and testing utilities

   Using pip (Alternative): bash pip install -e .

Credential Configuration

Securely store your necessary access keys in a file named .env within the project root:

BLOOM_API_URL= BLOOM_API_TOKEN=

Operational Usage

Integration with Cursor IDE

To allow the Cursor IDE to leverage this MCP backend:

1. Navigate to Cursor's configuration panel (Settings -> MCP).
2. Initiate the addition of a new MCP server instance.

3. Input the following configuration schema:

   • Alias: "Bloom Growth Connector"
   • Interface Type: Command
   • Execution Command: uv run --project /absolute/path/to/repo/ --env-file /absolute/path/to/repo/.env bloomy-server

   Crucial Note: Ensure that /absolute/path/to/repo/ accurately points to the directory where this project resides (e.g., /home/user/projects/bloom-growth-mcp/).

Launching the Service

Start the MCP server process using the designated entry point:

bash bloomy-server

Debugging and Schema Verification

For real-time monitoring of protocol interactions and debugging purposes, utilize the official MCP inspector tool:

bash npx @modelcontextprotocol/inspector bloomy-server

Recommended Workflow Enhancements

For a streamlined, automated development lifecycle, consider adopting these auxiliary utilities:

• direnv: For dynamic, directory-scoped environment variable management.
• uv: For superior speed in dependency resolution and installation.

Setting up direnv:

1. Install direnv (e.g., via a package manager).

2. Create a .envrc file in the project root to define secrets: bash export BLOOM_API_URL=your_secure_url export BLOOM_API_TOKEN=your_secret_token

3. Execute direnv allow to permit the shell to load these variables automatically upon directory entry.

This synergy between direnv and uv creates an optimized environment for managing secrets and software dependencies.

Exposed MCP Interfaces

AI agents are granted access to the following operational interfaces:

Tools (Actions)

• get_query_details: Retrieves granular metadata for any specified GraphQL query.
• get_mutation_details: Retrieves granular metadata for any specified GraphQL mutation.
• execute_query: Executes a provided GraphQL statement (query or mutation) alongside its required variables.
• get_authenticated_user_id: Fetches the unique identifier for the currently authorized user session.

Resources (Data Access Points)

• bloom://queries: Provides a catalog enumeration of all accessible query definitions.
• bloom://mutations: Provides a catalog enumeration of all accessible mutation definitions.

Internal Structure

src/ └── bloomy_mcp/ ├── init.py # Package initialization module ├── client.py # Core implementation for GraphQL communication ├── formatters.py # Utilities for data transformation and output shaping ├── introspection.py # Logic handling schema discovery ├── operations.py # Abstraction layer for operation definition/parsing └── server.py # Primary MCP server listener component

Third-Party Dependencies

• mcp[cli]: Framework for the Model Context Protocol server.
• gql: Client library for composing GraphQL requests.
• httpx: Asynchronous HTTP request handler.
• pyyaml: For potential configuration file processing.