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 bridges local 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 the modular refactor; the Automation Agent is currently documented as an orchestration playbook rather than a meta-tool. Add them as src/tools/*.ts modules to complete the set.

Related MCP server: Tyra Advanced Memory MCP Server

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 the Server, 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 the intercept 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 to stdout. All diagnostics (server/security/routing logs) go to stderr so the 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 mcpServers entry 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, so always use an absolute path.

• Any console.log/process.stdout.write in tool code corrupts the JSON-RPC stream. 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 once the 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: ToolMeta and execute(args), then add a case to the switch in src/router.ts (wrap the call in withSecurityGuard). Export its definition from toolDefinitions for ListTools.

• Security policy: mark a tool sensitive by setting category: "web3" or "productivity" in SENSITIVE_CATEGORIES (src/core/types.ts). Set SECURITY_MODE.interactiveConfirmation = true in src/middleware/security.ts to require a real client "Allow" prompt instead of the simulation.

• Build output: build/ is generated; it is safe to delete and regenerate with npm run build.