aljaz/dvmcp
1
0
Fork 0
mirror of https://github.com/aljazceru/dvmcp.git synced 2025-12-17 13:24:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: single kind approach

Browse Source
This commit is contained in:
gzuuus
2025-02-08 19:05:27 +01:00
parent dc45e8d3de
commit c5adb8c33d
1 changed files with 116 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
docs/dvmcp-spec.md
View File

@@ -38,15 +38,22 @@ The protocol consists of four main phases:
## Event Kinds ## Event Kinds
This specification defines how to use existing DVM event kinds (5600-7000) for MCP integration: Following NIP-90 conventions, this specification defines these event kinds:
| Kind | Description | | Kind | Description |
| ---- | ------------------------------- | | ---- | ------------------------ |
| 5600 | Tool discovery request | | 5600 | DVM-MCP Bridge Requests |
| 6600 | Tool catalog response | | 6600 | DVM-MCP Bridge Responses |
| 5601 | Tool execution request | | 7000 | Job Feedback |
| 6601 | Tool execution response |
| 7000 | Job feedback and payment status | Operations are differentiated using the `c` tag, which specifies the command being executed:
| Command Value | Type | Kind | Description |
| --------------------- | -------- | ---- | ----------------------------------------- |
| list-tools | Request | 5600 | Request available tools catalog |
| list-tools-response | Response | 6600 | Returns available tools and their schemas |
| execute-tool | Request | 5600 | Request execution of a specific tool |
| execute-tool-response | Response | 6600 | Returns the results of tool execution |
## Service Discovery ## Service Discovery
@@ -62,30 +69,81 @@ Service providers SHOULD announce their DVM capabilities using NIP-89 handler in
}, },
"tags": [ "tags": [
["d", "<dvm-announcement/random-id>"], ["d", "<dvm-announcement/random-id>"],
["k", "5600"], // Tool discovery ["k", "5600"],
["k", "5601"], // Tool execution
["capabilities", "mcp-1.0"], ["capabilities", "mcp-1.0"],
["t", "mcp"] ["t", "mcp"]
] ]
} }
``` ```
### Tool Discovery in Service Announcements
DVMs SHOULD include their available tools directly in their kind:31990 announcement events. This enables immediate tool discovery and execution without requiring an additional request/response cycle. Here's an example of a complete announcement:
```json
{
"kind": 31990,
"pubkey": "<dvm-pubkey>",
"content": {
"name": "MCP Tools DVM",
"about": "AI and computational tools via MCP",
"tools": [
{
"name": "summarize",
"description": "Summarizes text input",
"inputSchema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text to summarize"
}
}
}
}
]
},
"tags": [
["d", "<dvm-announcement/random-id>"],
["k", "5600"],
["capabilities", "mcp-1.0"],
["t", "mcp"],
["t", "summarize"]
]
}
```
This direct tool listing allows clients to:
1. Execute tools immediately without a discovery step
2. Filter for specific tool capabilities using relay queries
3. Make better decisions about DVM selection based on available tools
4. Reduce network overhead for simple integrations
DVMs MAY fall back to the `list-tools` command (described in the Tool Discovery section) in cases where:
- The tool list is too extensive to include in the announcement
- Tools are dynamically generated or change frequently
- Additional runtime metadata is needed for tool discovery
- The full tool schema would make the announcement too large
### Required Tags ### Required Tags
- `d`: A unique identifier for this announcement that should be maintained consistently for announcement updates - `d`: A unique identifier for this announcement that should be maintained consistently for announcement updates
- `k`: The event kinds this DVM supports (must include 5600 and 5601 for MCP support) - `k`: The event kind this DVM supports (5600 for MCP bridge requests)
- `capabilities`: Must include "mcp-1.0" to indicate MCP protocol support - `capabilities`: Must include "mcp-1.0" to indicate MCP protocol support
- `t`: Should include "mcp" to aid in discovery - `t`: Should include "mcp", and also tool names, to aid in discovery
### Tool Discovery Request (kind: 5600) ### Tool Discovery
Clients discover available tools by sending a kind 5600 event. This initiates the tool discovery process. Clients can also discover available tools by sending a request:
```json ```json
{ {
"kind": 5600, "kind": 5600,
"content": "", "content": "",
"tags": [ "tags": [
["c", "list-tools"],
["output", "application/json"], ["output", "application/json"],
["bid", "<msat-amount>"] ["bid", "<msat-amount>"]
] ]
@@ -98,9 +156,7 @@ The `p` tag MAY be included to target a specific provider:
["p", "<provider-pubkey>"] ["p", "<provider-pubkey>"]
``` ```
### Tool Catalog Response (kind: 6600) The DVM MUST respond with a kind 6600 event:
The DVM MUST respond with a kind 6600 event that lists all available tools and their specifications:
```json ```json
{ {
@@ -139,36 +195,22 @@ The DVM MUST respond with a kind 6600 event that lists all available tools and t
} }
] ]
}, },
"tags": [["e", "<tool-discovery-req-event-id>"]] "tags": [
["c", "list-tools-response"],
["e", "<tool-discovery-req-event-id>"]
]
} }
``` ```
The tool catalog response preserves the full MCP tool definition format, allowing clients to understand:
- Required and optional parameters
- Parameter types and constraints
- Expected response formats
Common parameter and properties types include:
- `string`: Text input with optional length constraints
- `number`: Floating-point values with optional ranges
- `integer`: Whole numbers with optional ranges
- `boolean`: True/false flags
- `array`: Lists of values with optional item constraints
- `object`: Nested parameter structures
## Job Execution ## Job Execution
Tools are executed through a request/response pair of events. Tools are executed through request/response pairs using kinds 5600/6600.
### Job Request (kind: 5601) ### Job Request
Tools are executed using a kind 5601 event:
```json ```json
{ {
"kind": 5601, "kind": 5600,
"content": { "content": {
"name": "<tool-name>", "name": "<tool-name>",
"parameters": { "parameters": {
@@ -177,7 +219,10 @@ Tools are executed using a kind 5601 event:
"max_tokens": 1024 "max_tokens": 1024
} }
}, },
"tags": [["p", "<provider-pubkey>"]] "tags": [
["c", "execute-tool"],
["p", "<provider-pubkey>"]
]
} }
``` ```
@@ -191,11 +236,11 @@ The content object MAY include:
- `timeout`: Maximum execution time in milliseconds - `timeout`: Maximum execution time in milliseconds
- `metadata`: Additional execution context - `metadata`: Additional execution context
### Job Response (kind: 6601) ### Job Response
```json ```json
{ {
"kind": 6601, "kind": 6600,
"content": { "content": {
"content": [ "content": [
{ {
@@ -218,29 +263,16 @@ The content object MAY include:
} }
}, },
"tags": [ "tags": [
["c", "execute-tool-response"],
["e", "<job-request-id>"], ["e", "<job-request-id>"],
["status", "success"] ["status", "success"]
] ]
} }
``` ```
The response content MUST include:
- `content`: An array of content blocks from the MCP tool execution
- `isError`: Boolean indicating if an error occurred
The response content MAY include:
- `metadata`: Additional context about the execution
Each content block MUST specify:
- `type`: The MIME type of the content
- `text`: The actual content data
## Job Feedback ## Job Feedback
DVMs use kind 7000 events to provide updates about job status and payment requirements. This enables proper handling of long-running jobs and payment flows. Following NIP-90, DVMs use kind 7000 events to provide updates about job status and payment requirements:
```json ```json
{ {
@@ -269,11 +301,11 @@ The `status` tag MUST use one of these values:
A typical payment flow proceeds as follows: A typical payment flow proceeds as follows:
1. Client submits job request 1. Client submits job request (kind:5600)
2. DVM responds requesting payment 2. DVM responds with payment requirement (kind:7000)
3. Client pays the invoice 3. Client pays the invoice
4. DVM processes the job 4. DVM indicates processing (kind:7000)
5. DVM returns results 5. DVM returns results (kind:6600)
## Error Handling ## Error Handling
@@ -295,9 +327,9 @@ DVMs MUST handle both protocol and execution errors appropriately:
For any error, DVMs MUST: For any error, DVMs MUST:
1. Send a kind 7000 event with status "error" 1. Send a kind:7000 event with status "error"
2. Include relevant error details in the content 2. Set isError=true in the kind:6600 response
3. Set isError=true in any kind 6601 response 3. Include relevant error details
## Implementation Requirements ## Implementation Requirements
@@ -322,19 +354,32 @@ sequenceDiagram
participant Server as MCP Server participant Server as MCP Server
Client->>Relay: Query kind:31990 Client->>Relay: Query kind:31990
Relay-->>Client: DVM handler info Relay-->>Client: DVM handler info with tools
Client->>DVM: kind:5600 (List Tools) alt Tools not in announcement
Client->>DVM: kind:5600, c:list-tools
DVM->>Server: Initialize + Get Tools DVM->>Server: Initialize + Get Tools
Server-->>DVM: Tool Definitions Server-->>DVM: Tool Definitions
DVM-->>Client: kind:6600 (Tool Catalog) DVM-->>Client: kind:6600, c:list-tools-response
end
Client->>DVM: kind:5601 (Execute Tool) Note over Client,DVM: Tool execution (same for both paths)
DVM-->>Client: (Optional)kind:7000 (payment-required) Client->>DVM: kind:5600, c:execute-tool
DVM-->>Client: kind:7000 (payment-required)
Client->>DVM: Payment Client->>DVM: Payment
DVM-->>Client: kind:7000 (processing) DVM-->>Client: kind:7000 (processing)
DVM->>Server: Execute Tool DVM->>Server: Execute Tool
Server-->>DVM: Results Server-->>DVM: Results
DVM-->>Client: kind:7000 (success) DVM-->>Client: kind:7000 (success)
DVM-->>Client: kind:6601 (Results) DVM-->>Client: kind:6600, c:execute-tool-response
``` ```
## Future Extensions
Additional commands can be added to support new MCP capabilities by defining new values for the `c` tag. This allows the protocol to evolve without requiring new event kinds. Future commands might include:
- Resource operations (list-resources, read-resource, etc.)
- Prompt operations (list-prompts, execute-prompt, etc.)
- Advanced tool operations (cancel-execution, batch-execute, etc.)
All such extensions MUST maintain the request/response kind relationship defined in NIP-90 (response kind = request kind + 1000) and use kind:7000 for job feedback.