Skip to main content
Glama
menmengleap

gravity-agent-mcp

by menmengleap
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesThe Khmer cultural / localization topic to look up.

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description does not disclose whether the tool is read-only, side effects, or any behavioral traits beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with a list of topics, no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple lookup tool with a single enumerated parameter; lacks details on return format but sufficient given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with enum and description; the description redundantly lists the enum values, adding minimal extra meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns localized Cambodian context for specific topics, and the sibling tool 'web3_blockchain_query' is unrelated, so no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage when Cambodian cultural context is needed for the listed topics, but no explicit guidance on when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

web3_blockchain_queryA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
networkYesTarget blockchain network.
walletAddressYesThe wallet address to inspect.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions 'simulated' balances, hinting at non-real data, but does not explicitly state that the tool is read-only, has no side effects, or any rate limits or authentication requirements. More transparency could improve agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and key details. Every word adds value, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple query tool with 2 parameters and no output schema, the description covers inputs (wallet address, network) and output (balances). However, it could briefly mention that the tool is read-only and safe to use, especially given no annotations. Still, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are documented. The description restates the network enum and wallet address but adds no new meaning beyond the schema. It does provide output context (returns balances) which is not param-related, but that doesn't enhance param semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Inspects an on-chain wallet address' and specifies the supported networks 'Ethereum, Solana'. It also mentions the return value 'simulated native + token balances'. This is specific and distinguishes it from the unrelated sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but provides no guidance on when to use it versus alternatives, no prerequisites, and no exclusions. Since only one sibling exists and it's unrelated, the lack of usage context is less critical, but still a gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedget_khmer_culture_context
    • First observedweb3_blockchain_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers