[Enh]: Support Persisted Documents as MCP tools

[JerryNixon]

What?

Allow developers to provide query.graphql files with predefined queries.

This becomes a custom MCP tool registered in the MCP server.

This is primarily the Hot Chocolate functionality.

Behavior

• Predefined queries are entities in dab-config.json.
• Predefined queries are parameterized like stored procedures.
• Predefined queries have only DAB execute permissions.
• Predefined queries are available through REST (/graphql/api/query-name).
• Predefined queries are precompiled by Hot Chocolate.
• Predefined queries are not in the GraphQL schema.
• Predefined queries run against standard GraphQL.
• Predefined queries do not override permissions.

Prerequisite

1. Hot Chocolate upgrade [Enh]: Upgrade Hot Chocolate #2826
2. MCP Endpoint [Enh]: Add MCP endpoint /mcp #2832

Why?

To enable persisted, complex queries against GraphQL.

• Also enables custom tools in MCP.

How

This is a feature of Hot Chocolate.

• Add persisted-document as new source.type enum
• Update JSON schema
• Register .graphql files with Hot Chocolate for REST
• Register .graphql files with Hot Chocolate for MCP
• Add CLI flags for dab add --mcp.custom-tool.enabled
• Add CLI flags for dab update --mcp.custom-tool.enabled
• Update CLI dab validate (see rules below)

Configuration

{
  "entities": {
    "MyCustomTool": {
      "source": {
        "object": "./query.graphql",
        "type": "persisted-document",
        "description": "", // not allowed for persisted-documents
        "parameters": "", // not allowed for persisted-documents
      },
      "graphql": {
        "enabled": false // true is not allowed
      },
      "rest": {
        "enabled": true // visible as rest endpoint
      },
      "mcp": { // new
        "custom-tool":{
          "enabled": true,
          "name": "" // not allowed for persisted documents
        } 
      },
      "permissions": {} // just like procs, only EXECUTE is allowed
    }
  }
}

New properties

• source.type is not new but adds new enum: persisted-document
• mcp.custom-tool.enabled registers the document as an MCP tool

Rules

1. source.type must be persisted-document.
2. source.object must point to a valid .graphql file.
3. rest.enabled and rest.path control REST endpoint registration.
4. mcp.custom-tool.enabled control MCP tool registration.
5. mcp.custo-tool.name is only valid for stored procedures
6. Predefined queries only support execute permission.
7. With source.type = persisted-document, the following are not allowed:
   • source.description This is defined inside the file
   • source.parameters This is defined inside the file
   • mappings (results can include nested fields)
   • graphql (query is presented as a REST endpoint)
   • permissions.include (query is presented as a REST endpoint)
   • permissions.exclude (query is presented as a REST endpoint)
   • permissions.policy (query is self-contained)
   • mcp.custom-tool.name This is defined inside the file

Command line

dab add User --mcp.custom-tool.enabled true
dab update User --mcp.custom-tool.enabled true