What is A2a Mcp Demo

a2a_mcp_demo is a demonstration project that showcases agent-to-agent (A2A) delegation using Google’s A2A protocol and the Model-Context Protocol (MCP). It allows a coding client agent to submit Dockerfiles for security review, which are then analyzed and patched by a security server agent using various static tools and best practices.

Use cases

Use cases for a2a_mcp_demo include automating security checks for Dockerfiles in CI/CD pipelines, enhancing the security posture of containerized applications, and providing developers with immediate feedback on potential vulnerabilities.

How to use

To use a2a_mcp_demo, clone the repository, set up the environment by copying and filling out the .env file with necessary values, start the Brave MCP server, and then build and run all services using Docker Compose. Finally, submit a Dockerfile for hardening through the client service.

Key features

Key features of a2a_mcp_demo include agent-to-agent delegation, security review of Dockerfiles, integration with static analysis tools like Hadolint and Trivy, and live best-practice lookups using the Brave API.

Where to use

a2a_mcp_demo can be used in software development environments, particularly in DevSecOps practices, where security reviews of containerized applications are essential.

A2A + MCP Docker Security Demo

Overview

This demo showcases agent-to-agent (A2A) delegation using Google’s A2A protocol and the Model-Context Protocol (MCP). A coding client agent submits a Dockerfile (or docker-compose YAML) for security review. The security server agent analyzes, hardens, and returns a patched config using static tools (Hadolint, Trivy) and live best-practice lookup (Brave/Playwright).

---

Prerequisites

• Docker & Docker Compose (for all services)
• Node.js (for MCP server, v16+ recommended)
• Python 3.8+
• npx (comes with Node.js)
• Brave API Key (get yours here)

---

Environment Setup

1. Copy the example env file:

   cp .env.example .env
   

2. Fill out all required values in .env:
   • BRAVE_API_KEY – Your Brave Search API key
   • LOGFIRE_TOKEN – For structured logging (see Logfire docs or use a placeholder for local)
   • A2A_BEARER_TOKEN – Any strong random string (used for agent-to-agent authentication)
   • BRAVE_MCP_SERVER_URL – Usually http://host.docker.internal:3000
   • (Optional) A2A_SERVER_URL, PYTHON_ENV as needed
3. Never commit your real .env! Only .env.example should be shared.

---

First Run Checklist

1. Clone the repo:

git clone
cd

2. **Prepare your Dockerfile for testing:**
   - Place it at `shared/sample.Dockerfile` or update the path as needed.
3. **Start the Brave MCP server:**
   ```sh
   npx -y @modelcontextprotocol/server-brave-search

• Leave this terminal running.

4. Build and start all services:

   docker compose up --build
   

5. Submit a Dockerfile for hardening:

   docker compose run client --dockerfile /app/shared/sample.Dockerfile
   

   (Adjust path if your Dockerfile is elsewhere.)

---

Troubleshooting

• Dockerfile not found: Ensure the path exists inside the client container.
• API key errors: Check your .env and MCP server status.
• Port conflicts: Make sure ports 3000 (MCP) and 8080 (server) are available.
• Logs: Use docker compose logs or Logfire for structured logs.
• Networking: If you’re not on Docker Desktop, you may need to adjust host.docker.internal.

---

Security Notes

• Never commit .env or real secrets.
• Bearer token is for dev/demo. Change it for production!
• All logs are structured JSON via Logfire.
• Containers run as non-root and drop unneeded Linux capabilities.

---

Sample Output

A successful run will output something like:

FROM python:3.12-slim
RUN pip install ...

# Hardened by server agent
# Here are some best practices for securing your Dockerfiles:
1. **Use Official Base Images** ...
...

---

How to Extend

• Add new MCP tools: Edit mcp.json and add new tool configs.
• Change static checks: Update server/agent.py logic.
• Plug in other best-practice sources: Modify the MCP integration or add new web search endpoints.

---

A2A Protocol Flow (Detailed)

sequenceDiagram
    participant User
    participant Client as A2A Client Agent
    participant Server as A2A Security Server Agent
    participant BraveMCP as Brave MCP Server

    %% Step 1: User submits Dockerfile
    User->>Client: Provide Dockerfile (any content)

    %% Step 2: Client validates server agent
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: Agent Card (capabilities, skills, authentication)
    Note right of Client: Validates required fields

    %% Step 3: Client submits Dockerfile for analysis
    Client->>Server: JSON-RPC POST / (method: tasks_send, params: raw_text)
    Note right of Client: Adds Bearer token for authentication

    %% Step 4: Server authenticates and parses task
    Server->>Server: Validate Bearer token
    Server->>Server: Parse Dockerfile

    %% Step 5: Server performs static checks
    Server->>Server: Simulate Hadolint/Trivy (static analysis)

    %% Step 6: Server queries Brave MCP for best practices
    Server->>BraveMCP: Web search for 'Dockerfile security best practices'
    BraveMCP-->>Server: Returns best-practice summary

    %% Step 7: Server hardens Dockerfile and prepares response
    Server->>Server: Patch Dockerfile (append best practices)
    Server-->>Client: JSON-RPC result: patched Dockerfile (plain text)

    %% Step 8: Client displays results
    Client-->>User: Show fixed Dockerfile & best practices

A2A Protocol Details:

• Agent Card validation ensures the server is a compliant A2A agent.
• All requests use Bearer authentication.
• Dockerfile content is never validated on the client—sent as-is.
• The server response is always a single text blob: the fixed Dockerfile with appended best practices.
• Brave MCP provides dynamic, up-to-date best-practice content.

Features

• Cross-agent task delegation using A2A protocol
• MCP tool for Dockerfile analysis and hardening
• Static and dynamic security checks
• JSON diff and issue reporting
• Full Docker-based reproducibility

Project Structure

a2a-docker-demo/
├── client/
│   ├── agent.py
│   ├── main.py
│   └── Dockerfile
├── server/
│   ├── agent.py
│   ├── main.py
│   └── Dockerfile
├── shared/
│   └── models.py
├── docker-compose.yml
├── requirements.txt
├── README.md

Quick Start

1. Clone and Set Up

git clone <repo-url>
cd <repo-directory>
cp .env.example .env

Edit .env and fill in required values:

• BRAVE_API_KEY (get from Brave Search)
• LOGFIRE_TOKEN (optional for local, required for Logfire)
• A2A_BEARER_TOKEN (any strong string for dev/demo)
• BRAVE_MCP_SERVER_URL (usually http://host.docker.internal:3000)

2. Prepare Your Dockerfile

• Place your Dockerfile at shared/sample.Dockerfile (or adjust the path as needed).

3. Start the Brave MCP Server

npx -y @modelcontextprotocol/server-brave-search

Leave this terminal running.

4. Build and Start All Services

docker compose up --build

5. Run the Client to Submit a Dockerfile

docker compose run client --dockerfile /app/shared/sample.Dockerfile

Replace the path if your Dockerfile is elsewhere.

---

Running the Client Standalone (Python)

You can run the Python client directly (outside Docker):

cd client
pip install -r ../requirements.txt
python main.py --dockerfile ../shared/sample.Dockerfile --server-url http://localhost:8080

Adjust the --dockerfile and --server-url as needed.

---

Running All Tests

From the project root, run:

bash run_all_tests.sh

This will execute all Python and shell-based tests. Ensure your .env is set up and required services are running (see above).

---

Environment Variables for local test enveironment copy these into your .env file

• BRAVE_API_KEY (required for Brave MCP server; set in .env)
• LOGFIRE_TOKEN (optional, for structured logging)
• A2A_BEARER_TOKEN (required for agent auth; just generate any random string, e.g., 32+ characters)
• BRAVE_MCP_SERVER_URL (URL for MCP server)
• A2A_SERVER_URL (optional, override for local testing)
• PYTHON_ENV (optional, e.g., development)
• PYTHONUNBUFFERED=1 (default for logs)
• MCP_SERVER_PORT=3000 (Brave MCP server)

---

Example .env File

Copy .env.example to .env and fill in your real values. Example:

# .env.example for A2A + MCP Docker Security Demo
# Copy this file to .env and fill in your real values

# Logfire (structured logging/observability)
LOGFIRE_TOKEN=your_logfire_write_token_here

# A2A Bearer token (for client/server auth)
A2A_BEARER_TOKEN=your_a2a_bearer_token_here  # Any random string, e.g. 32+ characters

# Brave MCP (web search for best practices)
BRAVE_API_KEY=your_brave_api_key_here
BRAVE_MCP_SERVER_URL=http://host.docker.internal:3000

# (Optional) Server URL override (for local testing)
A2A_SERVER_URL=http://host.docker.internal:8080

# (Optional) Client/Server environment
PYTHON_ENV=development

Reference this section when setting up your environment.

---

Troubleshooting

• Dockerfile not found: Ensure the path exists inside the client container.
• API key errors: Check your .env and MCP server status.
• Port conflicts: Make sure ports 3000 (MCP) and 8080 (server) are available.
• Logs: Use docker compose logs or Logfire for structured logs.
• If the MCP server is not reachable: Ensure you started it with npx -y @modelcontextprotocol/server-brave-search and .env is correct.
• If you change .env: Restart both the MCP server and all Docker containers.

---

Project Structure

a2a-docker-demo/
├── client/
│   ├── agent.py
│   ├── main.py
│   └── Dockerfile
├── server/
│   ├── agent.py
│   ├── main.py
│   └── Dockerfile
├── shared/
│   └── models.py
├── docker-compose.yml
├── requirements.txt
├── README.md

---

How to Extend

• Add new MCP tools: Edit mcp.json and add new tool configs.
• Change static checks: Update server/agent.py logic.
• Plug in other best-practice sources: Modify the MCP integration or add new web search endpoints.

---

CI/CD

• Add your preferred pipeline to automate tests (see .github/workflows/ if present)

---

Security & Logging

• All logs use structured JSON format (see Logfire integration)
• Containers run as non-root, drop unneeded Linux capabilities

---

For more details, see the PRD and specs in this repo.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

TODO

• [ ] When updating Markdown checklists for A2A compliance, always use green check marks (✅) to indicate completed items, not just [x]. This applies to task lists in a2a-task.md and similar files.

Environment Variables

• BRAVE_API_KEY (required for Brave MCP server; set in .env)
• PYTHONUNBUFFERED=1 (default for logs)
• MCP_SERVER_PORT=3000 (Brave MCP server)

Endpoints

• Server (Security Agent):
  • POST /a2a/tasks/send — Analyze and harden Dockerfile
  • GET /.well-known/agent.json — Agent Card

Testing

• End-to-end: Client submits Dockerfile, server returns patched version and JSON diff
• Latency target: ≤ 20s round-trip
• ≥80% high/critical issues resolved (simulated)

Sample Dockerfile

Place a file like this at shared/sample.Dockerfile:

FROM python:3.8
ADD . /app
RUN pip install -r requirements.txt  # Use only the root requirements.txt for all dependencies
CMD ["python", "main.py"]

Troubleshooting

• If the MCP server is not reachable, ensure you have started it with npx -y @modelcontextprotocol/server-brave-search and that your .env has the correct API key and BRAVE_MCP_SERVER_URL.
• For Docker containers to access the MCP server running on your host, use http://host.docker.internal:3000 as the server URL in .env.
• If you see connection errors, check that the MCP server terminal shows it is running and listening on port 3000.
• If you change .env, restart both the MCP server and your Docker containers.

CI/CD

• Add your preferred pipeline to automate tests (see .github/workflows/ if present)

Security & Logging

• All logs use structured JSON format (see Logfire integration)
• Containers run as non-root, drop unneeded Linux capabilities

---

For more details, see the PRD and specs in this repo.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.