convez.ai
MCP Server
RagavRida

agentsmcp

RagavRida/agentsmcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Context-sync protocol for AI agents. Persistent memory, async messaging, codebase indexing. One-command setup.

Instalação

$npx convez-ai RagavRida/agentsmcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

AgentMailbox

Cut your AI agent's context tokens by 90%. One command to set up. Zero config files to edit.

npm version npm downloads PyPI npm langgraph CI License: MIT skills.sh

🌐 Website · ☁️ Cloud API · 📖 Docs


The Problem

Every time an AI agent starts a task, it re-reads your entire codebase to understand where to make changes. For a 10,000-file repo, that's 200,000+ tokens per session — just to figure out the architecture.

Multiply that by 50 developers, each running multiple agents daily:

Without AgentMailboxWith AgentMailbox
Tokens per session start~200,000~5,000–15,000
Daily cost (50 devs)~$47/day~$3.50/day
Session start latency30–60 seconds2–5 seconds
Context across restarts❌ Lost✅ Persistent
Agent-to-agent messaging❌ Custom plumbing✅ Built-in

How It Works

AgentMailbox is a context-sync protocol for AI agents. It sits beneath your agent framework and provides:

  1. Codebase Indexing — A CI bot statically analyzes your code (zero LLM cost) and pushes ~40-token summaries per file to the server. Agents read summaries instead of raw source.
  2. Knowledge Graph — Agents persist relationships (files → symbols → decisions) that survive restarts and are searchable by any agent.
  3. Smart Briefings — When an agent starts a task, it calls session_start("Add OAuth") and gets back a targeted JSON briefing with relevant files, stale-file warnings, and architecture context.
  4. Async Messaging — Agents leave messages for each other in threads (TO/CC/BCC), enabling parallel multi-agent workflows without blocking.

Quick Start — One Command

npx agentsmcp init

That's it. The wizard:

  1. Detects your MCP clients (Claude Desktop, Cursor, Continue)
  2. Opens GitHub login in your browser — one click to authorize
  3. Writes the config to each client (backs up existing configs first)
  4. Done. Restart your MCP client.

Scripted / CI-friendly:

# Fully unattended — GitHub OAuth
npx agentsmcp init --yes --github --all

# Use an existing API key
npx agentsmcp init --api-key sk_live_xxx --all

# Just one client
npx agentsmcp init --api-key sk_live_xxx --client cursor

After restart, your agent has all 24 MCP tools available — persistent memory, async messaging, codebase search, and more.

Platform Integration Guides

Add to Settings → MCP → Add (or let npx agentsmcp init do it):

{
  "mcpServers": {
    "agentsmcp": {
      "command": "npx",
      "args": ["-y", "agentsmcp"],
      "env": {
        "AGENTSMCP_AGENT_ID": "cursor@local",
        "AGENTSMCP_SERVER": "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
        "AGENTSMCP_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentsmcp": {
      "command": "npx",
      "args": ["-y", "agentsmcp"],
      "env": {
        "AGENTSMCP_AGENT_ID": "claude@desktop",
        "AGENTSMCP_SERVER": "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
        "AGENTSMCP_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}
claude mcp add agentsmcp -- npx -y agentsmcp

Set environment variables:

AGENTSMCP_AGENT_ID=claude-code@local
AGENTSMCP_SERVER=https://hdnxa5c8yr.us-east-1.awsapprunner.com
AGENTSMCP_API_KEY=sk_live_YOUR_KEY
npx skills add RagavRida/agentsmcp

Same config shape: command: npx, args: ["-y", "agentsmcp"] with the three env vars: AGENTSMCP_AGENT_ID, AGENTSMCP_SERVER, AGENTSMCP_API_KEY.

Python

pip install agentsmcp
from agentmailbox import AgentMailbox

agent = AgentMailbox(
    agent_id="my-agent@app",
    server="https://hdnxa5c8yr.us-east-1.awsapprunner.com",
    api_key="sk_live_YOUR_KEY",
)

# Send & receive
await agent.send("other-agent@app", {"task": "analyze data"})
messages = await agent.receive()

# Context graph
await agent.upsert_node(id="file:main.py", type="file", name="main.py",
                        description="Entrypoint")
result = await agent.query_graph("main")

# Codebase index
await agent.upsert_index(key="file:main.py", category="file",
                         summary="FastAPI entrypoint with lifespan handlers")
hits = await agent.search_index("FastAPI", category="file")

JavaScript / TypeScript

npm install agentsmcp
import { AgentMailbox } from "agentsmcp";

const agent = new AgentMailbox({
  agentId: "my-agent@app",
  server: "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
  apiKey: "sk_live_YOUR_KEY",
});

await agent.send("other@app", { task: "done", result: data });
const { messages } = await agent.receive();

// Context graph
await agent.upsertNode({ id: "file:server.ts", type: "file", name: "server.ts" });
const { nodes, edges } = await agent.queryGraph("server");

// Codebase index
await agent.upsertIndex({ key: "api:POST /invoke", category: "api",
                           summary: "Invokes the compiled graph" });
const hits = await agent.searchIndex("invoke", "api");

LangGraph

npm install agentsmcp-langgraph @langchain/langgraph
import { AgentsmcpSaver } from "agentsmcp-langgraph";

const checkpointer = new AgentsmcpSaver({
  server: "https://hdnxa5c8yr.us-east-1.awsapprunner.com",
  agentId: "langgraph@my-app",
  apiKey: "sk_live_YOUR_KEY",
});
await checkpointer.connect();

const graph = workflow.compile({ checkpointer });
await graph.invoke(input, { configurable: { thread_id: "session-abc" } });

Architecture

┌────────────────────────────────────────────────────────────────┐
│                        Your Agents                             │
│  Claude Desktop  │  Cursor  │  Python Script  │  LangGraph     │
└────────┬─────────┴────┬─────┴───────┬─────────┴───────┬────────┘
         │ MCP          │ MCP         │ SDK             │ Saver
         ▼              ▼             ▼                 ▼
┌────────────────────────────────────────────────────────────────┐
│                   AgentMailbox Server                           │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ Messaging│  │ Knowledge │  │ Codebase │  │   Context     │  │
│  │ Threads  │  │   Graph   │  │  Index   │  │  Compression  │  │
│  └──────────┘  └───────────┘  └──────────┘  └──────────────┘  │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────────────────┐│
│  │Rate Limit│  │  GitHub   │  │ Multi-tenant Scoped Storage  ││
│  │& Auth    │  │  OAuth    │  │   SQLite (local) │ Postgres   ││
│  └──────────┘  └───────────┘  └──────────────────────────────┘│
└────────────────────────────────────────────────────────────────┘
         │                                              │
    ┌────▼────┐                                    ┌────▼────┐
    │  SQLite │  (single dev, zero config)         │Postgres │  (cloud, multi-tenant)
    └─────────┘                                    └─────────┘

MCP Tools (24 tools)

CategoryToolWhat it does
Sessionagentsmcp_session_startSmart context briefing — graph + index + stale detection
agentsmcp_context_briefingTargeted briefing for a specific task
Messagingagentsmcp_sendSend a message to another agent
agentsmcp_receiveGet unread messages with full thread context
agentsmcp_reply_allReply to all participants on a thread
agentsmcp_mark_readMark a thread as read
agentsmcp_threadsList all threads
agentsmcp_syncSync full context for a thread
agentsmcp_unreadPeek at unread without consuming
agentsmcp_participantsGet participants and roles
Graphagentsmcp_upsert_nodePersist a knowledge graph node
agentsmcp_add_edgeConnect two nodes with a typed edge
agentsmcp_query_graphKeyword search + N-hop traversal
Indexagentsmcp_upsert_indexRegister/update a codebase summary
agentsmcp_get_indexExact-key lookup
agentsmcp_search_indexKeyword search with category filter
agentsmcp_check_stalenessBatch hash check for stale files
agentsmcp_rollup_moduleAggregate file summaries into modules
Gitagentsmcp_git_commitCreate a commit
agentsmcp_git_diffView staged/unstaged changes
agentsmcp_git_logView commit history
agentsmcp_git_branchBranch operations
Annotationsagentsmcp_annotate_fileAdd inline code annotations
agentsmcp_get_annotationsRead annotations for a file

Self-Hosted

Free, unlimited, MIT-licensed. SQLite by default, Postgres when you need it.

# SQLite (zero config)
npx agentsmcp-server

# Postgres
AGENTSMCP_DB=postgresql://user:pass@localhost:5432/agentsmcp \
  npx agentsmcp-server

# With auth
AGENTSMCP_API_KEY=your-secret npx agentsmcp-server

# With LLM compression
ANTHROPIC_API_KEY=sk-ant-xxx npx agentsmcp-server

See deploy/AWS.md for a Docker + App Runner walkthrough.

Free Tier (Cloud)

ResourceLimit
Agents10
Messages / day500
Threads100
Retention7 days
API keys2

Need more? Self-host for unlimited — same code, MIT licensed.

API Reference

MethodEndpointDescription
POST/auth/registerSign up, get API key
POST/auth/githubGitHub OAuth login
GET/auth/meYour account + usage
GET/auth/keysList active API keys
POST/auth/keysMint an additional key
DELETE/auth/keys/:keyIdRevoke a key
POST/agents/registerRegister an agent
POST/messages/sendSend message (TO/CC/BCC)
POST/messages/reply-allReply to all participants
GET/mailbox/:agentIdList threads
GET/mailbox/:agentId/unreadUnread messages + context
POST/mailbox/:agentId/readMark thread as read
GET/threads/:threadIdThread detail
GET/threads/:threadId/syncAssembled context frame
GET/healthHealth check
MethodEndpointDescription
POST/mailbox/:agentId/graph/nodesUpsert a node
DELETE/mailbox/:agentId/graph/nodes/:nodeIdDelete a node + edges
POST/mailbox/:agentId/graph/edgesAdd a directed edge
DELETE/mailbox/:agentId/graph/edgesRemove an edge
GET/mailbox/:agentId/graph/query?q=…&limit=N&depth=DSearch + traversal
MethodEndpointDescription
POST/mailbox/:agentId/indexUpsert an entry
GET/mailbox/:agentId/index?q=…&category=…&limit=NKeyword search
GET/mailbox/:agentId/index/:keyExact-key lookup
DELETE/mailbox/:agentId/index/:keyDelete an entry
POST/mailbox/:agentId/index/check-stalenessBatch hash check
POST/mailbox/:agentId/index/rollupAggregate file summaries

Development

# Install + type-check + test
npm ci && npx tsc --noEmit && npm test

# End-to-end smoke test
npm run smoke:e2e

# LangGraph adapter
cd langgraph && npm install && npm run build && npm test

# Python SDK
cd sdk-py && pip install -e ".[dev]" && pytest -q

163 tests across 16 test files. Full matrix (JS + LangGraph + Python 3.10/3.11/3.12) runs in CI on every push.

Contributing

Contributions welcome! Particularly wanted:

  • Framework adapters — CrewAI, OpenAI Agents SDK, AutoGen, Vercel AI SDK
  • Compressor adapters — Gemini, Bedrock, Ollama (Claude and OpenAI already ship)
  • Storage adapters — Redis, DynamoDB (SQLite and Postgres are done)
  • Demos — Multi-day workflows, cross-language pipelines, agent-in-the-loop patterns

See the Contributing Guide for process details.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados