puppygraph

This MCP server, PuppyGraph, enables Claude Desktop and other MCP-compatible interfaces to query a PuppyGraph graph using both Gremlin and Cypher. It connects to Neo4j Bolt for Cypher queries and to a WebSocket endpoint for Gremlin traversal, and it can retrieve graph structure and schema information from multiple endpoints. Available tools include puppygraph_query for executing queries, puppygraph_schema for schema/details, and puppygraph_status to check connection health. Each tool also has an mcp__ prefixed variant for compatibility with certain LLM platforms. Start the MCP server via your preferred environment (e.g., Claude Desktop) and use these tools to perform graph queries, inspect schema, or verify connection status. Example usage includes running Cypher or Gremlin queries against the connected PuppyGraph instance and querying for schema details to understand the graph structure.

Prerequisites:

• Node.js 18+
• A running PuppyGraph instance (or fallback testing setup)

Installation steps:

1. Clone the repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Start the server:

npm start

5. Optionally configure environment variables directly in your MCP config (see mcp_config example for variable names and defaults).

Tips and common considerations:

• Ensure Node.js 18+ is installed and available in your PATH.
• Adjust PUPPYGRAPH_URL, PUPPYGRAPH_GREMLIN_URL, and schema-related env vars to point to your actual PuppyGraph endpoints.
• The config supports running the MCP server under Claude Desktop or via your own MCP runner; you can set env vars directly in the MCP config.
• If a connection fails, the server will report clear errors and may still serve queries via alternative endpoints when available.
• For Gremlin, ensure the WebSocket URL begins with ws:// or wss:// and that the Gremlin service is accessible.
• When testing locally, you can use the provided tools (puppygraph_query, puppygraph_schema, puppygraph_status) to verify connectivity before running complex queries.