Gravity Agent

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

#	Pillar	Status	Where it lives
1	Localization & Khmer Culture Agent	✅ Implemented	src/tools/khmerCulture.ts
2	Hyper-Personalized Productivity	🧩 Stub (see note)	src/tools/ (to add)
3	Decentralized / Web3 Agent	✅ Implemented	src/tools/web3.ts
4	Cross-Platform Automation Agent	📘 Playbook	docs/automation-playbook.md
5	Security & Privacy Guard	✅ Implemented	src/middleware/security.ts
6	Intelligent Routing	✅ Implemented	src/router.ts
7	Zero-Configuration	✅ One-line config	claude_desktop_config.json

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.

---

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

Tool	Category	Sensitive?	Description
get_khmer_culture_context	culture	No	Returns localized Cambodian context for a topic (legal_business_registration, khmer_etiquette, phnom_penh_zones).
web3_blockchain_query	web3	Yes	Inspects a wallet address on Ethereum/Solana; returns simulated native + token balances. Address format is regex-validated.

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.