Hasura GraphQL

🚀 Advanced Features

This project offers advanced features for seamless integration with Hasura GraphQL. Here's a guide on how to install, run, and configure the server.

🚀 Quick Start

📦 Installation

Run the following command to install the project dependencies:

pnpm install

🏗️ Build the Service

Compile the TypeScript code to the dist directory:

pnpm run build

🚀 Run the Server

Start the server using the following command, specifying the Hasura GraphQL endpoint and an optional admin secret:

# Run using pnpm script
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# Or run directly with Node.js
node dist/index.js <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

Example:

pnpm start https://my-hasura.cloud/v1/graphql mysecretkey123

Or

node dist/index.js https://my-hasura.cloud/v1/graphql mysecretkey123

If you don't need an admin secret (using default role permissions):

pnpm start https://my-hasura.cloud/v1/graphql

After the server starts, it will attempt an initial schema decompilation, connect to the STDIO transport, and log status messages to stderr. It listens for MCP JSON-RPC requests on stdin and sends responses to stdout.

💻 Usage with MCP Clients (e.g., Cursor, Claude Desktop)

To connect this server to an MCP client like Cursor:

1. Find the absolute paths:

   • Node executable: Run which node in the terminal.
   • Server script: Navigate to the mcp-hasura-advanced directory and run pwd. Append /dist/index.js to the result.
   • Project directory: The output of pwd.

2. Configure the client: Open your client configuration file (e.g., settings.json for Cursor, claude_desktop_config.json for Claude Desktop).

3. Add a server entry: Add an entry under the appropriate key (e.g., the cursor.customMcpServers array for Cursor, the mcpServers object for Claude Desktop).

Example Cursor settings.json:

{
  // ... other settings ...
  "cursor.customMcpServers": [
    // ... other servers ...
    {
      "name": "My Advanced Hasura Server", // Name displayed in the Cursor UI
      "command": "/path/to/your/node", // <<< Absolute path from 'which node'
      "args": [
        "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to the compiled script
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< Your endpoint
        "YOUR_ADMIN_SECRET"                                   // <<< Your secret (remove if no secret is needed)
      ],
      // Optional but recommended for consistent module resolution:
      "cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< Absolute path to the project root
    }
  ]
}

Example Claude Desktop claude_desktop_config.json:

{
    "mcpServers": {
        // ... other servers ...
        "hasura-advanced": { // Key used internally by Claude
            "command": "/path/to/your/node",
            "args": [
                "/absolute/path/to/mcp-hasura-advanced/dist/index.js",
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",
                "YOUR_ADMIN_SECRET"
            ],
            // Optional but recommended for consistent module resolution:
            "cwd": "/absolute/path/to/mcp-hasura-advanced"
        }
    }
}

✨ Advanced Features

⚙️ Set Environment Variables

You can add custom environment variables in package.json:

{
  "env": {
    "NODE_ENV": "production",
    "MY_SECRET": "my-secret-value"
  }
}

🌐 Use a Different Port

To change the default port (3000), specify it at runtime:

pnpm start --port=3001 <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

✅ Validate Configuration

Before starting the server, validate all configurations:

pnpm run lint

🛠️ Troubleshooting

If you encounter issues, check the following:

• Ensure the Hasura endpoint is a valid URL.
• Check if the admin secret is correctly configured.
• Review the console output for error messages.

📚 Appendix

⌨️ Command Line Options

pnpm start [options] <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]
Options:
  --port=VALUE          Customize the server port (default: 3000)
  --verbose             Enable verbose logging

📁 Example Project Structure

mcp-hasura-advanced/
├── dist/              # Compiled output directory
├── src/
│   ├── index.ts      # Main application file
│   └── schema.ts     # GraphQL schema definition
└── package.json       # Dependency and script configuration

🤝 Contribution Guidelines

To contribute to the project, fork the repository and make changes on the dev branch. Before submitting, ensure all tests pass.

📄 License

[Insert license information here]