Skip to main content
Glama
gravity-agent-mcp
by menmengleap

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

#

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.


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

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.

Available Tools

2 tools
get_khmer_culture_contextA

Returns localized Cambodian context for a topic. Topics: legal_business_registration, khmer_etiquette, phnom_penh_zones.

Inputs: topic (required).

web3_blockchain_queryA

Inspects an on-chain wallet address on a given network (Ethereum, Solana). Returns simulated native + token balances.

Inputs: network (required), walletAddress (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools are completely unrelated: one provides Cambodian cultural context, the other queries blockchain wallets. There is no overlap in purpose or functionality, so an agent can easily distinguish them.

    Naming Consistency4/5

    Both tools use descriptive names with underscores, but one starts with 'get_' and the other with 'web3_', introducing a slight inconsistency in naming style. However, both are clear and predictable.

    Tool Count2/5

    With only 2 tools covering disparate domains (culture and blockchain), the server feels underdeveloped. Either the server should focus on one domain with more tools, or additional related tools should be added to justify the mix.

    Completeness3/5

    Each individual tool appears adequate for its narrow purpose, but the server lacks a coherent domain, making it impossible to assess full lifecycle coverage. There are no obvious gaps within each tool, but the set as a whole is not comprehensive.

    Related MCP Connectors

    Related MCP Servers