gravity-agent-mcp

gravity-agent-mcp

A next-generation Omni-Agent system built on the Model Context Protocol (MCP).gravity-agent-mcp is an intelligent, secure, context-aware assistant that bridgeslocal cultural nuance (Khmer / Cambodian) with automation and Web3 capabilities,exposed to clients like Claude Desktop over a stdio transport.

1. The 7 Core Pillars

Note: Pillars 2/4 are not yet shipped as live tools. create_calendar_event(productivity) and khmer_greeting were scaffolding and were removed during themodular refactor; the Automation Agent is currently documented as an orchestrationplaybook rather than a meta-tool. Add them as src/tools/*.ts modules to completethe set.

2. Tech Stack

• Language: TypeScript (strict) / Node.js ≥ 18
• Framework: @modelcontextprotocol/sdk
• Transport: JSON-RPC 2.0 over Stdio
• Client: Claude Desktop (or any MCP-compatible client)

3. Project Structure

gravity-agent-mcp/
├── src/
│   ├── index.ts              # Entry point: Server init + Stdio transport
│   ├── router.ts             # Pillar 6 — dispatch (switch-case) + tool registry
│   ├── core/
│   │   └── types.ts          # Shared contract (ToolMeta, ToolResult, ToolHandler…)
│   ├── middleware/
│   │   └── security.ts       # Pillar 5 — withSecurityGuard() interceptor
│   └── tools/
│       ├── khmerCulture.ts   # Pillar 1 — get_khmer_culture_context
│       └── web3.ts           # Pillar 3 — web3_blockchain_query
├── docs/
│   └── automation-playbook.md# Pillar 4 — orchestration guide
├── build/                    # Compiled output (generated by tsc)
├── package.json
└── tsconfig.json

The entry point (src/index.ts) does only three things: initialize theServer, attach ListTools/CallTool handlers (delegating to src/router.ts),and connect over Stdio. All tool logic, guarding, and routing live in src/.

4. Tools

Sensitive tools pass through the Security & Privacy Guard, which logs theintercept and runs a (simulated) confirmation gate before executing.

5. Setup

Prerequisites

• Node.js ≥ 18 and npm.

Install & build

npm install        # install dependencies (SDK + TypeScript)
npm run build      # compile src/ → build/  (tsc)

Run (stdio)

npm start          # node build/index.js

The server reads JSON-RPC requests from stdin and writes responses tostdout. All diagnostics (server/security/routing logs) go to stderr sothe JSON-RPC stream on stdout stays clean — this is required for stdio MCP.

6. Connect to Claude Desktop (Zero-Config, Pillar 7)

Edit your claude_desktop_config.json (macOS:~/Library/Application Support/Claude/claude_desktop_config.json;Windows: %APPDATA%\Claude\claude_desktop_config.json). Add a mcpServersentry pointing at the compiled build/index.js with an absolute path:

{
  "mcpServers": {
    "gravity-agent-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/gravity-agent-mcp/build/index.js"
      ]
    }
  }
}

Common pitfalls (these cause the "pipe broke" error / no tool icon):

• Pointing args at index.ts instead of the compiled build/index.js(Node can't run TypeScript directly).
• Using a relative path — Claude Desktop launches from a different cwd, soalways use an absolute path.
• Any console.log/process.stdout.write in tool code corrupts the JSON-RPCstream. This project logs only via console.error.
• Forgetting to run npm install before npm run build (missing SDK).

Restart Claude Desktop after editing the config; the tools/plug icon appears oncethe server handshakes successfully.

7. Example: call a tool over JSON-RPC

Send newline-delimited JSON-RPC messages on stdin:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_khmer_culture_context","arguments":{"topic":"khmer_etiquette"}}}

Expected tools/call result (truncated):

{
  "content": [
    { "type": "text", "text": "{ \"topic\": \"khmer_etiquette\", \"title\": \"…\", \"dos\": […], \"donts\": […] }" }
  ]
}

For web3_blockchain_query, the server logs a [SECURITY] Intercepted … (sensitive: true)line to stderr and runs the simulated confirmation before returning balances.

8. Development notes

• Add a tool: create src/tools/<name>.ts exporting definition: ToolMetaand execute(args), then add a case to the switch in src/router.ts(wrap the call in withSecurityGuard). Export its definition fromtoolDefinitions for ListTools.
• Security policy: mark a tool sensitive by setting category: "web3" or"productivity" in SENSITIVE_CATEGORIES (src/core/types.ts). SetSECURITY_MODE.interactiveConfirmation = true in src/middleware/security.tsto require a real client "Allow" prompt instead of the simulation.
• Build output: build/ is generated; it is safe to delete and regeneratewith npm run build.