Azure / Azure/data-api-builder

[Enh]: Support Persisted Documents as MCP tools

Open
#2,840 0 comments 0 reactions 1 assignee Claimed by @souvikghosh04 View on GitHub
2.3
Dominant language
C#
Stars
1.5k
Forks
370
Avg merge
3d 17h
Merged PRs (30d)
8

Description

## 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 #2826
2. MCP Endpoint #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

```json
{
"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

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.