MCP vs A2A: what is the difference? (with code)

mkdir mcp-vs-a2a && cd mcp-vs-a2a
npm init -y
npm install @a2a-js/sdk @modelcontextprotocol/client express
npm install -D typescript tsx @types/node @types/express

// The "brain" of the analyst: plain code, so no API key is needed.
// In a real agent this is the one function you swap for a model.
export interface Commit {
  sha: string;
  date: string;
  author: string;
  subject: string;
}

export function summarize(commits: Commit[], todos: string): string {
  const groups: Record<string, Commit[]> = {
    Features: [],
    Fixes: [],
    Other: [],
  };
  for (const c of commits) {
    const s = c.subject.toLowerCase();
    const key = /\b(add|new|support|introduce)\b/.test(s)
      ? "Features"
      : /\b(fix|bug|handle|patch)\b/.test(s)
        ? "Fixes"
        : "Other";
    groups[key]!.push(c);
  }
  const lines = ["# Release notes", ""];
  for (const [title, list] of Object.entries(groups)) {
    if (!list.length) continue;
    lines.push(
      `## ${title}`,
      ...list.map((c) => `- ${c.subject} (${c.sha})`),
      "",
    );
  }
  const open = todos.split("\n").filter((l) => /TODO|FIXME/.test(l));
  lines.push(
    `## Known gaps (${open.length})`,
    ...open.map((l) => `- ${l}`),
  );
  return lines.join("\n");
}

// MCP is how this agent uses TOOLS. A2A (below) is how other
// agents talk to THIS agent.
async function gatherFromRepo(
  limit: number,
): Promise<{ commits: Commit[]; todos: string }> {
  const mcp = new Client({ name: "repo-analyst", version: "1.0.0" });
  await mcp.connect(
    new StreamableHTTPClientTransport(new URL(SCOUT_URL)),
  );
  try {
    const log = await mcp.callTool({
      name: "git_log",
      arguments: { limit },
    });
    const todos = await mcp.callTool({
      name: "list_todos",
      arguments: {},
    });
    const commits = (log.structuredContent as { commits: Commit[] })
      .commits;
    const todoText = (
      todos.content as { type: string; text: string }[]
    )
      .map((c) => c.text)
      .join("\n");
    return { commits, todos: todoText };
  } finally {
    await mcp.close();
  }
}

// The agent card is the A2A business card: who I am, what I can
// do, where to reach me.
const card: AgentCard = {
  name: "Repo Analyst",
  description:
    "Reads a git repository and writes release notes. Delegate to it, don't micromanage it.",
  supportedInterfaces: [
    {
      url: `http://localhost:${PORT}/`,
      protocolBinding: "JSONRPC",
      tenant: "",
      protocolVersion: A2A_PROTOCOL_VERSION,
    },
  ],
  provider: { organization: "DevAIper", url: "https://devaiper.com" },
  version: "1.0.0",
  capabilities: {
    streaming: true,
    pushNotifications: false,
    extensions: [],
    extendedAgentCard: false,
  },
  securitySchemes: {},
  securityRequirements: [],
  defaultInputModes: ["text"],
  defaultOutputModes: ["text"],
  skills: [
    {
      id: "release-notes",
      name: "Release notes",
      description:
        "Summarise recent commits and open TODOs into release notes.",
      tags: ["git", "release"],
      examples: ["Write release notes for the last 10 commits"],
      inputModes: ["text"],
      outputModes: ["text"],
      securityRequirements: [],
    },
  ],
  documentationUrl: "",
  signatures: [],
};

const WORKING = TaskState.TASK_STATE_WORKING;
const COMPLETED = TaskState.TASK_STATE_COMPLETED;
const FAILED = TaskState.TASK_STATE_FAILED;

class AnalystExecutor implements AgentExecutor {
  async execute(ctx: RequestContext, bus: ExecutionEventBus) {
    const say = (state: TaskState, text?: string) =>
      bus.publish(statusUpdate(ctx, state, text));

    bus.publish(newTask(ctx)); // 1. a task is born
    try {
      say(WORKING, "Reading the repository through MCP tools..."); // 2.
      const { commits, todos } = await gatherFromRepo(10);
      say(WORKING, `Got ${commits.length} commits. Writing notes...`);

      const notes = summarize(commits, todos); // 3. the result
      bus.publish(artifactEvent(ctx, "release-notes.md", notes));
      say(COMPLETED);
    } catch (err) {
      const why = (err as Error).message;
      say(FAILED, `Could not reach the repo tools: ${why}`);
    }
  }

  // This demo finishes in about a second: nothing to cancel.
  async cancelTask() {}
}

// The SDK's message shapes are verbose (generated from the protocol
// definition). We wrap them once here and forget about them.
import { type Part, Role, TaskState } from "@a2a-js/sdk";
import { AgentEvent, type RequestContext } from "@a2a-js/sdk/server";
import { randomUUID } from "node:crypto";

export const textPart = (
  value: string,
  mediaType = "text/plain",
) => ({
  content: { $case: "text" as const, value },
  metadata: undefined,
  filename: "",
  mediaType,
});

const now = () => new Date().toISOString();

// A message from the user (what the orchestrator sends).
export const userRequest = (text: string) => ({
  tenant: "",
  message: {
    messageId: randomUUID(),
    role: Role.ROLE_USER,
    parts: [textPart(text)],
    taskId: "",
    contextId: "",
    extensions: [],
    metadata: undefined,
    referenceTaskIds: [],
  },
  configuration: undefined,
  metadata: undefined,
});

// 1. A task is born, in state "submitted".
export const newTask = (ctx: RequestContext) =>
  AgentEvent.task({
    id: ctx.taskId,
    contextId: ctx.contextId,
    status: {
      state: TaskState.TASK_STATE_SUBMITTED,
      timestamp: now(),
      message: undefined,
    },
    artifacts: [],
    history: [ctx.userMessage],
    metadata: undefined,
  });

// 2. A status update, optionally with a plain-words message.
export const statusUpdate = (
  ctx: RequestContext,
  state: TaskState,
  text?: string,
) =>
  AgentEvent.statusUpdate({
    taskId: ctx.taskId,
    contextId: ctx.contextId,
    status: {
      state,
      timestamp: now(),
      message: text
        ? {
            role: Role.ROLE_AGENT,
            messageId: randomUUID(),
            parts: [textPart(text)],
            taskId: ctx.taskId,
            contextId: ctx.contextId,
            extensions: [],
            metadata: undefined,
            referenceTaskIds: [],
          }
        : undefined,
    },
    metadata: undefined,
  });

// 3. The result: a named file (artifact) with its content.
export const artifactEvent = (
  ctx: RequestContext,
  name: string,
  markdown: string,
) =>
  AgentEvent.artifactUpdate({
    taskId: ctx.taskId,
    contextId: ctx.contextId,
    artifact: {
      artifactId: randomUUID(),
      name,
      description: name,
      parts: [textPart(markdown, "text/markdown")],
      metadata: undefined,
      extensions: [],
    },
    lastChunk: true,
    append: false,
    metadata: undefined,
  });

// Join the text parts of a message or artifact (what the orchestrator prints).
export const textOf = (parts: Part[] | undefined) =>
  (parts ?? [])
    .map((p) => (p.content?.$case === "text" ? p.content.value : ""))
    .join("");

const handler = new DefaultRequestHandler(
  card,
  new InMemoryTaskStore(),
  new AnalystExecutor(),
);
const app = express();
app.use(
  `/${AGENT_CARD_PATH}`,
  agentCardHandler({ agentCardProvider: handler }),
);
app.use(
  "/",
  jsonRpcHandler({
    requestHandler: handler,
    userBuilder: UserBuilder.noAuthentication,
  }),
);
app.listen(PORT, "127.0.0.1", () =>
  console.error(
    `repo-analyst (A2A) on http://localhost:${PORT}/  card: /${AGENT_CARD_PATH}`,
  ),
);

import { ClientFactory } from "@a2a-js/sdk/client";
import { taskStateToJSON } from "@a2a-js/sdk";
import { textOf, userRequest } from "./a2a-helpers.js";

const AGENT_URL = process.env.AGENT_URL ?? "http://localhost:41241";

// A2A step 1: find the agent by reading its card.
const client = await new ClientFactory().createFromUrl(AGENT_URL);
const card = await client.getAgentCard();
console.log(
  `Found agent: ${card.name} (${card.skills.map((s) => s.name).join(", ")})`,
);

// A2A step 2: delegate a goal in plain language, watch the task.
const stream = client.sendMessageStream(
  userRequest("Write release notes for the last 10 commits"),
);

for await (const event of stream) {
  const e = event.payload;
  switch (e?.$case) {
    case "task":
      console.log(`[task] ${e.value.id} created`);
      break;
    case "statusUpdate": {
      const st = e.value.status!;
      const msg = textOf(st.message?.parts);
      console.log(`[status] ${taskStateToJSON(st.state)} ${msg}`);
      break;
    }
    case "artifactUpdate": {
      const art = e.value.artifact!;
      console.log(`\n--- artifact: ${art.name} ---`);
      console.log(textOf(art.parts));
      break;
    }
  }
}

# terminal 1: the MCP server
REPO_SCOUT_REPO=/path/to/your/repo npm run http   # in the repo-scout project

# terminal 2: the analyst (A2A server)
npx tsx src/analyst.ts

# terminal 3: the orchestrator (A2A client)
npx tsx src/orchestrator.ts

curl -s localhost:41241/.well-known/agent-card.json

{
    "name": "Repo Analyst",
    "description": "Reads a git repository and writes release notes. Delegate to it, don't micromanage it.",
    "supportedInterfaces": [
        {
            "url": "http://localhost:41241/",
            "protocolBinding": "JSONRPC",
            "tenant": "",
            "protocolVersion": "1.0"
        }
    ],
    "provider": {
        "organization": "DevAIper",
        "url": "https://devaiper.com"
    },
    "version": "1.0.0",
    "capabilities": {
        "streaming": true,
        "pushNotifications": false,
        "extensions": [],
        "extendedAgentCard": false
    },
...

Found agent: Repo Analyst (Release notes)
[task] e575eb72-eaae-40b8-9cbd-0bab9ebcf06d created
[status] TASK_STATE_WORKING Reading the repository through MCP tools...
[status] TASK_STATE_WORKING Got 3 commits. Writing notes...

--- artifact: release-notes.md ---
# Release notes

## Features
- Add shipping calculation (07aa2bf)
- Add discount codes (0870206)

## Other
- Initial commit: cart total (ca4a3bf)

## Known gaps (3)
- discount.js:1:// TODO: support percentage discounts
- shipping.js:1:// TODO: free shipping above 50
- shipping.js:2:// FIXME: handle international addresses
[status] TASK_STATE_COMPLETED 

Found agent: Repo Analyst (Release notes)
[task] f4366165-d7ce-4795-93be-35e5c25979d5 created
[status] TASK_STATE_WORKING Reading the repository through MCP tools...
[status] TASK_STATE_FAILED Could not reach the repo tools: fetch failed