Tools Workspace (Automation & MCP)

The Tools workspace provides the automation backbone for the Elo Orgânico project. It centralizes specialized Model Context Protocol (MCP) servers and infrastructure scripts designed to enhance developer productivity, ensure environment parity through multi-stage Docker builds, and enable secure, high-context AI-native engineering workflows.

MCP Ecosystem

Model Context Protocol (MCP) Ecosystem

The Elo Orgânico monorepo features a specialized, containerized MCP ecosystem. It exposes structured development capabilities and codebase contexts to LLM clients (such as the Antigravity CLI or external agents) via a secure, high-performance gateway network.

Zero-Dependency TypeScript Adapters

Standard CLI-based MCP servers communicate via standard input/output (stdio) streams. To expose them securely over the network, every service is packaged with a custom TypeScript wrapper (sse-adapter.ts) running on Fastify v5. This adapter implements two distinct network protocols:

• Traditional Server-Sent Events (SSE): Establishes a uni-directional stream via GET /sse and accepts client messages via POST /messages, piping events directly to the underlying subprocess stdin.
• Streamable Stateless HTTP (POST /sse): A custom transactional adapter that simulates stateless request-response. It buffers stdout lines from the child process, extracts JSON-RPC payloads, and resolves the HTTP request only when it captures the specific JSON-RPC response id matching the request. Notifications (requests lacking an id) receive an immediate 204 No Content response.

Integrated Context Servers

GitHub MCP Server

Overview & Project Utility

The GitHub MCP server connects our containerized development environment directly to the GitHub API. It enables AI agents to coordinate version control tasks, manage issue lifecycles, and perform code search or automated pull request reviews.

• Upstream: http://elo-mcp-github:3001/github/sse

Tool Registry & Capabilities

• search_repositories: Search for repositories matching a query.
• create_repository: Create a new GitHub repository.
• search_code: Search for code snippets across repositories.
• search_issues: Search for issues and pull requests.
• search_commits: Search for commit histories.
• create_branch: Create a new Git branch.
• list_branches: Retrieve list of all branches in the repository.
• update_pull_request_branch: Update a pull request branch to stay in sync with the base.
• get_commit: Retrieve detailed information for a specific commit.
• list_commits: List commits on a branch.
• get_tag: Get metadata details for a Git tag.
• list_tags: List all tags in a repository.
• get_file_contents: Retrieve contents of a specific file or directory.
• create_or_update_file: Write or update a file in the repository.
• delete_file: Delete a file from a branch.
• push_files: Commit and push multiple files in a single transaction.
• issue_read: View details of a specific issue.
• issue_write: Create or update an issue.
• sub_issue_write: Add sub-issue relationships.
• add_issue_comment: Add a comment to an issue or pull request.
• list_issues: List issues in the repository.
• list_issue_types: List supported issue types.
• pull_request_read: View details of a specific pull request.
• create_pull_request: Open a new pull request.
• update_pull_request: Update metadata of a pull request.
• list_pull_requests: List pull requests in the repository.
• merge_pull_request: Merge a pull request using specified merge method.
• add_comment_to_pending_review: Add comments to a pending pull request review.
• add_reply_to_pull_request_comment: Reply to an inline comment in a pull request review.
• pull_request_review_write: Submit a pull request review.
• request_copilot_review: Request a review from GitHub Copilot.
• assign_copilot_to_issue: Assign GitHub Copilot to resolve an issue.
• get_latest_release: Get the latest published release.
• get_release_by_tag: Retrieve a release by its Git tag.
• list_releases: List releases in the repository.
• get_label: Get information about a repository label.
• list_repository_collaborators: List collaborators for a repository.
• get_me: Get information about the authenticated user.
• get_teams: List teams in the organization.
• get_team_members: List members of a specific team.
• fork_repository: Fork a repository to your account.

Context7 MCP Server

Overview & Project Utility

The Context7 MCP server interfaces with the Context7 API to provide real-time documentation searches. This is a critical context engine for AI agents to query the latest API syntaxes, usage patterns, and version changes of our core dependencies (React 19, Fastify 5, Three.js) without relying on stale model training data.

• Upstream: http://elo-mcp-context7:3002/context7/sse

Tool Registry & Capabilities

• resolve-library-id: Resolves a package or library name to a Context7-compatible unique ID.
• query-docs: Retrieves up-to-date documentation sections, API methods, and code examples for a resolved library ID.

Browser MCP Server (Playwright)

Overview & Project Utility

The Browser MCP server is a headless Google Chrome instance managed via Playwright. It allows AI agents to interact directly with the project's web interfaces, enabling visual regression checks, console error auditing, accessibility tree inspection, and network request sniping in a fully containerized sandbox.

• Upstream: http://elo-mcp-browser:3003/browser/sse
• Host-to-Container Routing: Automatically rewrites destination URLs targeting localhost or 127.0.0.1 to host.docker.internal to route requests successfully from the container bridge to the host machine (e.g., accessing Docusaurus on port 3002 or React app on port 5173).

Tool Registry & Capabilities

• browser_navigate: Navigate to a specified URL.
• browser_navigate_back: Navigate back to the previous page in history.
• browser_wait_for: Pause execution until a specific selector or page state is resolved.
• browser_click: Simulate clicking a DOM element matching a selector.
• browser_hover: Hover the mouse pointer over a specified element.
• browser_type: Type text into an input field.
• browser_fill_form: Fill out multiple input fields in a form.
• browser_select_option: Select options in a dropdown select element.
• browser_press_key: Simulate pressing a specific keyboard key.
• browser_drag: Drag an element and drop it onto another element.
• browser_drop: Drop a file or element at the target location.
• browser_file_upload: Upload a file to a file input element.
• browser_take_screenshot: Capture and save a screenshot of the current page viewport.
• browser_snapshot: Capture a snapshot of the page's DOM or accessibility tree.
• browser_console_messages: Retrieve logs and errors emitted by the browser console.
• browser_network_requests: List all network requests initiated by the page.
• browser_network_request: Retrieve details of a specific network request/response.
• browser_tabs: List active browser tabs.
• browser_handle_dialog: Accept, dismiss, or respond to native browser dialog popups.
• browser_evaluate: Execute custom JavaScript code within the context of the page.
• browser_run_code_unsafe: Execute arbitrary Node.js code within the container sandbox.
• browser_close: Close the browser instance.
• browser_resize: Resize the viewport dimensions.

Docker Hub MCP Server

Overview & Project Utility

The Docker Hub MCP server manages interactions with the Docker Hub registry. It allows the system to discover images, check tags, and inspect container repository metadata, ensuring that our monorepo infrastructure remains aligned with upstream container images.

• Upstream: http://elo-mcp-dockerhub:3004/dockerhub/sse

Tool Registry & Capabilities

• search: Search for repositories on Docker Hub.
• getRepositoryInfo: Retrieve metadata information for a specific repository.
• updateRepositoryInfo: Update metadata details of a repository.
• checkRepository: Check if a repository exists on Docker Hub.
• listRepositoryTags: Retrieve list of all tags for a repository.
• getRepositoryTag: Get detailed metadata for a specific image tag.
• checkRepositoryTag: Verify if a specific image tag exists.
• listNamespaces: List namespaces accessible by the user.
• getPersonalNamespace: Get the authenticated user's personal namespace.
• listAllNamespacesMemberOf: List all organizations/namespaces the user is a member of.
• dockerHardenedImages: Fetch a list of recommended security-hardened base images.

AI Agents (Docker)

Containerized AI Agents

The tools/agents workspace provisions GitHub Copilot and Google Antigravity CLIs as long-running Docker services. This eliminates manual CLI installations on developer host machines and guarantees environment parity between local workstations and cloud VMs.

Architecture Overview

The agent containers run inside the same elo-mcp-net bridge network as the MCP gateway, communicating with it via internal DNS routing. No host-level port exposure is required for inter-service communication.

Directory Layout

tools/agents/
├── .env.agents.example     # Environment variable template (tracked)
├── .env.agents             # Secrets (Git-ignored)
├── compose.yaml            # Orchestration for both agent containers
├── mcp_config.json         # Unified MCP config (injected into both containers)
├── skills/                 # Shared agent skills (injected into both containers)
│   ├── code-expert/
│   └── doc-expert/
├── copilot/
│   ├── Dockerfile          # GitHub CLI + Copilot CLI + Docker CLI
│   ├── data/               # Git-ignored: Copilot session state and auth tokens
│   └── gh-config/          # Git-ignored: GitHub CLI credentials and extensions
└── antigravity/
    ├── Dockerfile          # Antigravity CLI + Docker CLI
    ├── data/               # Git-ignored: conversations, brain, log buffers
    ├── settings.json       # Version-controlled TUI settings (container paths)
    ├── statusline.sh       # CLI status bar script
    └── title.sh            # CLI window title script

Configuration Injection Strategy

All configuration is injected via Docker bind mounts at container startup. No files are baked into the image layers, ensuring that settings changes take effect without rebuilding images.

Mount Source	Container Destination	Purpose
../../	/workspace	Full monorepo working directory
./skills/	/workspace/.agents/skills	Shared skills visible to both CLIs
./mcp_config.json	/workspace/.agents/mcp_config.json	Unified MCP endpoint configuration
./antigravity/data/	/root/.gemini/antigravity-cli/	Persistent runtime data
./antigravity/settings.json	/root/.gemini/antigravity-cli/settings.json	Version-controlled TUI settings
./copilot/data/	/root/.copilot/	Persistent Copilot session state
./copilot/gh-config/	/root/.config/gh/	Persistent GitHub CLI credentials
/var/run/docker.sock	/var/run/docker.sock	Docker-out-of-Docker orchestration
~/.ssh	/root/.ssh (read-only)	Host SSH keys for Git operations
~/.gitconfig	/root/.gitconfig (read-only)	Host Git identity

MCP Network Connectivity

Inside the agent containers, MCP services are resolved via the host gateway using the custom alias elo.internal.tools.mcp mapped to host-gateway on port 3005. This allows the agent stack to start completely independently of the MCP stack.

{
  "mcpServers": {
    "github":    { "url": "http://elo.internal.tools.mcp:3005/github/sse" },
    "context7":  { "url": "http://elo.internal.tools.mcp:3005/context7/sse" },
    "browser":   { "url": "http://elo.internal.tools.mcp:3005/browser/sse" },
    "dockerhub": { "url": "http://elo.internal.tools.mcp:3005/dockerhub/sse" }
  }
}

Independent Boot Sequence

The agent and MCP stacks are network-decoupled. Either stack can be started or stopped independently. The agents will automatically connect to the MCP gateway when the MCP stack is running.

Lifecycle Commands

Command	Action
pnpm agents:up	Build images (if needed) and start both agent containers in detached mode.
pnpm agents:down	Stop and remove the agent containers.
pnpm agents:reset	Full teardown with volume removal followed by a clean rebuild and restart.
pnpm antigravity:auth	Execute Google OAuth authentication flow in the active terminal window.
pnpm copilot:auth	Execute GitHub OAuth device authentication flow in the active terminal window.

VS Code Task Integration

Agent CLIs are invoked via docker exec tasks registered in .vscode/tasks.json. Tasks are labeled with a [Docker] or [Host] prefix to distinguish containerized execution from host-level global installations.

Task Label	Execution Target
[Docker] Antigravity CLI	docker exec -it agent-antigravity agy
[Docker] Copilot CLI	docker exec -it agent-copilot copilot
[Host] Antigravity CLI	Host-global agy installation
[Host] Copilot CLI	Host-global copilot installation

Authentication and Session Persistence

Both CLIs use OAuth device-flow authentication. To authenticate the containerized agents, execute the direct authentication scripts (pnpm copilot:auth or pnpm antigravity:auth) in your active terminal. The CLI outputs a URL and a verification code. The developer opens the URL in the host browser, completes the authorization flow, and the resulting tokens are written to the container's home directory.

Persistent Storage & No-Rebuild Architecture

Because the credentials directories are bind-mounted to the host:

• agent-copilot mounts ./copilot/data/ to /root/.copilot/ and ./copilot/gh-config/ to /root/.config/gh/
• agent-antigravity mounts ./antigravity/data/ to /root/.gemini/antigravity-cli/

Any authentication token generated during the first-time setup is directly written to these host directories in real time. As a result:

• No container rebuild is required: Rebuilding or restarting the container does not erase credentials, as the container reads tokens dynamically from the mounted host volumes.
• Host Isolation: While the container is authenticated, these credentials do not leak into the host user's global folders (e.g., ~/.gemini or ~/.config/gh), ensuring a clean separation between the container stack and host-global CLI installations.
• Automated Synced Access: As soon as the user completes the device authorization flow, the credentials immediately become active and functional. No manual file copies or restarts are necessary.

note

The data/ and gh-config/ directories are Git-ignored. They exist only on the developer's local machine and are never committed to the repository.

AI Security & Network

Isolated Infrastructure & Network Routing

Security and environment predictability are maintained through isolated Docker bridge networks (elo-agents-net for agents and elo-mcp-net for MCP tools), preventing unauthorized cross-network access.

Gateway & Routing Configuration

• Fastify HTTP Proxy Gateway: A lightweight Fastify v5 server (elo-mcp-gateway) running on Node.js serves as the entrypoint. It exposes port 3005 to the host machine. Using @fastify/http-proxy, it proxies path prefixes (e.g., /github) to the respective backend containers.
• Network-Level CORS & SSE Handling: The gateway intercepts OPTIONS requests and injects appropriate CORS headers globally. It disables default HTTP timeouts on proxies to prevent active Server-Sent Events (SSE) connections from dropping during long-running tasks.
• Internal Domain Routing: Within the MCP stack, the gateway is aliased as elo.internal.tools.mcp. Agent containers running in separate network namespaces can route requests directly through http://elo.internal.tools.mcp:3005/[service]/sse via the host bridge mapping.
• Host-to-Container Bridge: Local development clients (such as the Google Antigravity CLI) communicate with the gateway from the host machine loopback interface using:

  http://localhost:3005/github/sse

• Buffered stdio Stream Mapping: The wrapper executes child processes locally, preventing stdout fragmentation. By checking JSON-RPC transaction ids line-by-line, the adapter resolves HTTP requests with complete, un-truncated payloads.

Engineering Guidelines

Rules of Engagement for AI Agents

The workspace defines strict behavioral logic for AI agents through structured context files. These guidelines ensure that all automated changes follow project-wide architectural standards and maintain technical integrity.

Operational Conventions

• Domain Core First: Modification of shared schemas or data models must originate in the core packages (Single Source of Truth) before being propagated to application layers.
• Strict Typing & Linting: Agents are strictly prohibited from using any or bypassing the project's rigorous TypeScript/ESLint configurations. Validation via typecheck is a mandatory step after code modification.
• Technological Minimalism: Avoid suggesting external dependencies unless no native or already-implemented solution exists within the current stack (Fastify, React, Zustand, Zod).
• Conventional Documentation: Documentation updates must follow a professional, senior tone, utilizing MDX features like Tabs for high-density information management.

Maintenance & Logic

Operational Logic and Maintenance

Standardized commands are provided for maintaining the automation layer and verifying workspace health across the monorepo.

Command	Engineering Responsibility
pnpm typecheck	Validates TypeScript integrity across scripts and MCP source code.
pnpm build	Full production build including MCP servers and automation tools.
pnpm clean	Aggressive workspace maintenance using npkill to prune legacy dependencies.

Workspace Orchestration

Command	Engineering Action
pnpm mcp:up	Launches the entire Dockerized gateway and backend MCP stack.
pnpm mcp:down	Tears down the gateway and MCP container environment.
pnpm mcp:reset	Aggressive stack wipe (volumes removed) followed by full container rebuild.

Workspace Structure

• tools/mcp/compose.yaml: Defines the container services, dependencies, volumes, and bridge networks.
• tools/mcp/gateway/: Contains the Fastify v5 HTTP proxy router server (server.ts and its Dockerfile).
• tools/mcp/infrastructure/: Holds individual multi-stage Dockerfiles and the zero-dependency sse-adapter.ts wrapper.
• tools/mcp/config/: Manages context-specific environments and secret configurations (e.g., .env.*.example files).