** ATTENTION: This codebase is no longer actively maintained. Due to observed limitations in model context memory handling for smaller models, the preferred architectural pattern has shifted towards deploying individual, containerized service providers rather than a single, monolithic routing mechanism. The source code remains accessible for historical reference or for those choosing to pursue this integrated server paradigm.

Model Context Protocol (MCP) Backend Service

This implementation adheres to the Model Context Protocol specification, furnishing interfaces for interacting with GitHub, GitLab, geospatial data retrieval (Google Maps), persistent state management (Memory), and automated web interaction through Puppeteer.

Architectural Blueprint

The core design employs a modular structure where each external utility is encapsulated as an independent plug-in. The central server acts as a singular dispatch hub, intelligently directing incoming requests to the corresponding specialized agent.

Key Capabilities

MCP Command Hub: A singular access point conforming to the MCP standard for all utility interactions.
Service Descriptor: An endpoint providing a comprehensive registry of all loaded services and their functional signatures.
Direct Utility Access: Granular routing paths allowing direct communication with individual tool backends.
Extensible Configuration: The design permits effortless introduction or abstraction of tool modules.

Integrated Toolsets

GitHub Interface: Facilitates interaction with GitHub entities: repositories, issue tracking, and search functions.
GitLab Interface: Manages interactions with GitLab projects, issue tracking, and CI/CD pipeline status.
Geospatial Utility: Supports location resolution (geocoding), routing calculations, and points-of-interest discovery.
Persistent Storage Agent: Offers reliable mechanisms for data serialization and retrieval.
Web Automation Engine: Leverages Puppeteer for tasks like screen capture, document rendering (PDF), and content extraction from web pages.

Initial Setup Guide

Pre-requisites

Python interpreter, version 3.8 or newer.
Node.js runtime, version 14 or newer.
Operation on a compatible Unix-like environment (e.g., RHEL derivatives, standard Linux, or macOS).

Installation Procedure

Obtain the repository source code: bash git clone https://github.com/yourusername/mcp-server.git cd mcp-server
Install Python dependencies: bash pip install -r requirements.txt
Install Node.js dependencies: bash npm install
Configure environment variables in a .env file: ``` SECRET_KEY=your-secure-key DEBUG=False

# GitHub Credentials GITHUB_TOKEN=your-github-access-token

# GitLab Credentials GITLAB_TOKEN=your-gitlab-access-token

# Google Maps Authorization GMAPS_API_KEY=your-maps-key

# Local Data Store Configuration MEMORY_DB_URI=sqlite:///memory.db

# Puppeteer Settings PUPPETEER_HEADLESS=true CHROME_PATH=/usr/bin/chromium-browser ```

Initiate the service: bash python app.py

Containerized Deployment Options

The service can be deployed using either Docker or Podman (Red Hat's container runtime).

Docker Workflow

Assuming Docker and docker-compose are configured:

Construct the container image: bash docker build -t mcp-server .
Execute the container: bash docker run -p 5000:5000 --env-file .env mcp-server
Utilizing docker-compose for orchestration:

Define configuration in docker-compose.yml: yaml version: '3' services: mcp-server: build: . ports: - "5000:5000" volumes: - ./data:/app/data env_file: - .env restart: unless-stopped

Then deploy: bash docker-compose up -d

Podman Workflow

Targeted for RHEL, CentOS, and Fedora environments:

Build the image with Podman: bash podman build -t mcp-server .
Run the isolated container: bash podman run -p 5000:5000 --env-file .env mcp-server
For persistent data volumes: bash mkdir -p ./data podman run -p 5000:5000 --env-file .env -v ./data:/app/data:Z mcp-server Note: The :Z flag is mandatory for proper SELinux context relabeling on secured systems.
Employing Podman Compose (requires separate installation): ```bash # Installation if missing pip install podman-compose

# Reuse the docker-compose.yml structure podman-compose up -d ```

Interacting with the MCP Backend

Central MCP Dispatcher

This is the primary entry point for unified, protocol-compliant requests.

Endpoint: POST /mcp/gateway

Input Payload Structure:

{
  "tool": "github",
  "action": "listRepos",
  "parameters": {
    "username": "octocat"
  }
}

Output Response Structure:

{
  "tool": "github",
  "action": "listRepos",
  "status": "success",
  "result": [
    {
      "id": 1296269,
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "owner": {
        "login": "octocat",
        "id": 1
      },
      ...
    }
  ]
}

Service Manifest Retrieval

Fetches the metadata detailing all integrated services and their functional parameters.

Endpoint: GET /mcp/manifest

Output Structure:

{
  "manifestVersion": "1.0",
  "tools": {
    "github": {
      "actions": {
        "listRepos": {
          "description": "Enumerate repositories belonging to a specified user or organization",
          "parameters": {
            "username": {
              "type": "string",
              "description": "Identifier for the GitHub user or organization"
            }
          },
          "returns": {
            "type": "array",
            "description": "Collection of repository metadata objects"
          }
        },
        ...
      }
    },
    ...
  }
}

Direct Interface Access

Individual utilities can be invoked directly via their dedicated endpoint prefixes:

Version Control (GitHub): `/tool/github/...
Version Control (GitLab): `/tool/gitlab/...
Mapping Data: `/tool/gmaps/...
State Management: `/tool/memory/...
Web Automation: `/tool/puppeteer/...

Consult the specific documentation for each tool for precise endpoint definitions.

Tool Specifications

GitHub Interface

Provides API access for repositories, issue tracking, and search operations.

Available Operations: - listRepos: Retrieve repository listings for a target entity. - getRepo: Fetch detailed metadata for a single repository. - searchRepos: Execute repository searches. - getIssues: Query issues associated with a repository. - createIssue: Provision a new issue within a repository.

GitLab Interface

Manages interactions with GitLab projects, issues, and CI/CD pipelines.

Available Operations: - listProjects: List all accessible projects for the authenticated session. - getProject: Retrieve specific project details. - searchProjects: Search across GitLab instances. - getIssues: Fetch issues associated with a designated project. - createIssue: Submit a new issue to a project. - getPipelines: Retrieve the status and history of project pipelines.

Geospatial Utility

Interfacing with Google Maps services for coordinate conversion, pathfinding, and location discovery.

Available Operations: - geocode: Translate a street address into latitude/longitude coordinates. - reverseGeocode: Translate geographic coordinates back into a human-readable address. - getDirections: Calculate routes between two defined points. - searchPlaces: Query the Google Places database. - getPlaceDetails: Retrieve in-depth data for a known place ID.

Persistent Storage Agent

Provides a key-value persistence layer for state preservation.

Available Operations: - get: Retrieve a stored data entry using its key. - set: Insert a new record or overwrite an existing one. - delete: Erase a data entry by its key. - list: Output all stored entries, supporting optional filtering criteria. - search: Execute full-text or structural searches within stored values.

Web Automation Engine

Implements headless browser functionality for tasks like captures and content extraction.

Available Operations: - screenshot: Capture an image of a specified URL. - pdf: Generate a portable document format file from a webpage. - extract: Scrape structured or unstructured data from a live web page.

Development Guidelines

Contributions for expansion are highly encouraged. To incorporate a new utility:

Establish a new file within the tools/ directory (e.g., tools/new_utility_agent.py).
Implement the new utility's functionalities following the established action pattern.
Update the central manifest configuration within app.py.
Register the new tool's API routing blueprint in tools/__init__.py.

Licensing

This software is distributed under the terms of the MIT License; refer to the LICENSE file for the full stipulations.

Acknowledgments

Gratitude is extended to: - The Model Context Protocol specification authors for the foundational standard. - Flask for providing the underlying web framework. - Puppeteer for enabling robust web automation capabilities.

WIKIPEDIA: A headless browser operates without a visible graphical user interface (GUI). These environments enable scripted, programmatic control over a web page, mimicking standard browser behavior but executed via command line or network services. They are crucial for validation tasks, as they accurately interpret HTML structure, CSS styling (layout, color, typography), and execute client-side JavaScript/AJAX—features often inaccessible via simpler fetching methods. Modern browser engines (Chrome/Firefox) integrated remote control APIs starting around 2017, diminishing the reliance on predecessors like PhantomJS.

== Primary Applications == The chief uses for headless browsing include:

Automated functional and regression testing for contemporary web applications. Generating static images (screenshots) of dynamic web content. Executing unit tests for complex JavaScript libraries that rely on DOM rendering. Automating complex user workflows on websites.

=== Secondary Utility === Headless environments are also valuable for sophisticated web harvesting (scraping). Google, for instance, recognized their utility in indexing content rendered via Ajax as early as 2009. Conversely, misuse scenarios exist, such as facilitating distributed denial-of-service (DDoS) attacks, artificially inflating advertisement views, or performing unauthorized automated account interactions (credential stuffing). However, traffic analysis from 2018 suggests that headless browsers are not disproportionately favored by malicious agents compared to standard browsers for common attacks like SQL injection or XSS.

== Execution Frameworks == Given native headless support across major browser platforms via APIs, several cross-browser automation interfaces have emerged:

Selenium WebDriver – Implements the W3C WebDriver standard. Playwright – A robust Node.js library supporting Chromium, Firefox, and WebKit. Puppeteer – A specialized Node.js utility focusing primarily on Chrome/Firefox automation.

=== Testing Implementations === Numerous quality assurance frameworks incorporate headless browsing capabilities:

Capybara frequently utilizes Headless Chrome or WebKit to simulate user interaction in test suites. Jasmine typically defaults to Selenium but supports integration with WebKit or Headless Chrome for browser-level testing. Cypress, a dedicated frontend testing platform. QF-Test, a GUI testing tool capable of leveraging headless environments.

=== Alternatives to Full Rendering === An alternative strategy involves utilizing libraries that simulate browser APIs without performing full graphical rendering. Deno incorporates browser APIs directly into its runtime. For Node.js environments, jsdom offers the most comprehensive DOM simulation. While these libraries support fundamental features (HTML parsing, basic JS execution, XHR), they often lack full DOM event fidelity and graphical rendering, leading to faster execution speeds than true headless instances.

unified-mcp-orchestrator

Author

AdamPippert

Quick Info

Actions

Tags