# gravity-agent-mcp

A next-generation **Omni-Agent** system built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
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`](https://www.npmjs.com/package/@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
```bash
npm install        # install dependencies (SDK + TypeScript)
npm run build      # compile src/ → build/  (tsc)
```

### Run (stdio)
```bash
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**:

```json
{
  "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:

```json
{"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):

```json
{
  "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`.