Add 'packages/mcp-spec/' from commit 'd06853c5e8'
git-subtree-dir: packages/mcp-spec git-subtree-mainline:02e421c1f1git-subtree-split:d06853c5e8
This commit is contained in:
David Soria Parra
commit
929275eddf
3 changed files with 4596 additions and 53 deletions
111
packages/mcp-spec/examples/completion.md
generated
Normal file
111
packages/mcp-spec/examples/completion.md
generated
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# Completion API
|
||||
The completion API provides ability for clients to request a
|
||||
set of completion options for a prompt argument or a resource template
|
||||
argument.
|
||||
|
||||
## Basic Completion: completion/complete
|
||||
The RPC method `completion/complete` is used for basic completion
|
||||
tasks. They reference either a prompt or a uri template.
|
||||
|
||||
### Client Requests
|
||||
#### Reference Example 1
|
||||
|
||||
The following example references a prompt with the name "weather-forecast".
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "completion/complete",
|
||||
"params": {
|
||||
"ref": {
|
||||
"type": "ref/prompt",
|
||||
"name": "weather-forecast"
|
||||
},
|
||||
"argument": {
|
||||
"name": "location",
|
||||
"value": "New"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Reference Example 2
|
||||
|
||||
The alternative is to reference a URI template of a resource:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "completion/complete",
|
||||
"params": {
|
||||
"ref": {
|
||||
"type": "ref/resource",
|
||||
"uri": "file://64e56d89-ba43-4664-87fc-ff6703527e3b/?as={mimeType}"
|
||||
},
|
||||
"argument": {
|
||||
"name": "mimeType",
|
||||
"value": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Server Responses
|
||||
|
||||
Responses can only contain up to 100 elements. The server should
|
||||
notify the client how many elements are there in total. If the
|
||||
server knows the *exact* amount, it should specifiy the amount in
|
||||
`total` as an `integer`. If the server does not know how many left,
|
||||
but knows there are more completions than returned, `total` should
|
||||
be set to `hasMore`. This can be useful when the server wants to
|
||||
make efficient database queries and limit the resultset. In cases
|
||||
where the server does not know if there are any left, for example
|
||||
when reading from a service that does not provide such information,
|
||||
it can set `total` to `unknown`. This should be avoided if possible.
|
||||
|
||||
#### Example Response with known total
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"completion": {
|
||||
"values": [
|
||||
"New York",
|
||||
"New Orleans",
|
||||
"New Delhi",
|
||||
"New Haven",
|
||||
"New Jersey"
|
||||
],
|
||||
"total": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example Response with unknown total
|
||||
The following case illustrates the case where the total
|
||||
is unknown, but the server knows there are more elements
|
||||
than returned:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"completion": {
|
||||
"values": [
|
||||
"New York",
|
||||
"New Orleans",
|
||||
"New Delhi",
|
||||
"New Haven",
|
||||
"New Jersey"
|
||||
],
|
||||
"hasMore": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
77
packages/mcp-spec/examples/prompts.md
generated
Normal file
77
packages/mcp-spec/examples/prompts.md
generated
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Prompt API
|
||||
The Prompt API provides a set of prompts with optional
|
||||
arguments and [autocompletion](completion.md) support.
|
||||
|
||||
## Listing Prompts
|
||||
The client can request a set of prompts
|
||||
from the server using the `prompts/list` call
|
||||
|
||||
A client request:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "prompts/list",
|
||||
"params": {}
|
||||
}
|
||||
```
|
||||
|
||||
And an appropriate server response
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"prompts": [
|
||||
{
|
||||
"name": "my-prompt",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "input",
|
||||
"description": "The input string",
|
||||
"required": false
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Running a prompt
|
||||
In order to run a prompt, the client issues
|
||||
a `prompts/get` command:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"method": "prompts/get",
|
||||
"params": {
|
||||
"name": "my-prompt",
|
||||
"arguments": {
|
||||
"input": "hello world"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
and it's respective response:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"result": {
|
||||
"description": "An optional description of the prompt.",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": {
|
||||
"type": "text",
|
||||
"text": "This is a templated prompt. You passed the argument 'hello world'"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
170
packages/mcp-spec/examples/workflow_diagrams.md
generated
Normal file
170
packages/mcp-spec/examples/workflow_diagrams.md
generated
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
# Example MCP workflow diagrams
|
||||
|
||||
Some illustrative sequence diagrams of various concepts that could be built as MCP servers.
|
||||
|
||||
**NOTE:** These are _examples_, not necessarily planned integrations!
|
||||
|
||||
### Google Drive Resource Requests
|
||||
|
||||
> a sequence diagram showing how resources would be requested from a Google Drive MCP server
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as MCP Client
|
||||
participant Server as Google Drive MCP Server
|
||||
participant GDrive as Google Drive API
|
||||
|
||||
Client->>+Server: initialize
|
||||
Server-->>-Client: InitializeResult
|
||||
Client->>Server: initialized
|
||||
|
||||
Client->>+Server: resources/list
|
||||
Server->>+GDrive: List files and folders
|
||||
GDrive-->>-Server: Files and folders list
|
||||
Server-->>-Client: ListResourcesResult
|
||||
|
||||
Client->>+Server: resources/read (file.txt)
|
||||
Server->>+GDrive: Get file contents
|
||||
GDrive-->>-Server: File contents
|
||||
Server-->>-Client: ReadResourceResult
|
||||
|
||||
opt Subscribe to folder updates
|
||||
Client->>+Server: resources/subscribe (folder/)
|
||||
Server-->>-Client: EmptyResult
|
||||
|
||||
loop While subscribed
|
||||
GDrive-->>Server: File change notification
|
||||
Server->>Client: notifications/resources/updated (folder/newfile.txt)
|
||||
|
||||
opt Read updated resource
|
||||
Client->>+Server: resources/read (folder/newfile.txt)
|
||||
Server->>+GDrive: Get file contents
|
||||
GDrive-->>-Server: File contents
|
||||
Server-->>-Client: ReadResourceResult
|
||||
end
|
||||
end
|
||||
|
||||
Client->>+Server: resources/unsubscribe (folder/)
|
||||
Server-->>-Client: EmptyResult
|
||||
end
|
||||
```
|
||||
|
||||
### Git MCP Server Tool Use
|
||||
|
||||
> an example of a Git MCP server, exposing a few Git commands as tool use for the LLM
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant LLM
|
||||
participant MCP Client
|
||||
participant MCP Server
|
||||
participant Git System as Git
|
||||
|
||||
User->>LLM: "Commit my changes and push"
|
||||
|
||||
LLM->>MCP Client: Request available tools
|
||||
MCP Client->>MCP Server: tools/list
|
||||
MCP Server-->>MCP Client: ListToolsResult (Git commands)
|
||||
MCP Client-->>LLM: Available Git tools
|
||||
|
||||
LLM->>MCP Client: tools/call (git status)
|
||||
MCP Client->>MCP Server: tools/call (git status)
|
||||
MCP Server->>Git System: git status
|
||||
Git System-->>MCP Server: status output
|
||||
MCP Server-->>MCP Client: CallToolResult (status)
|
||||
MCP Client-->>LLM: Git status result
|
||||
|
||||
Note over LLM: LLM analyzes status, decides to commit
|
||||
|
||||
LLM->>MCP Client: tools/call (git commit -m "Update files")
|
||||
MCP Client->>MCP Server: tools/call (git commit -m "Update files")
|
||||
MCP Server->>Git System: git commit -m "Update files"
|
||||
Git System-->>MCP Server: commit result
|
||||
MCP Server-->>MCP Client: CallToolResult (commit)
|
||||
MCP Client-->>LLM: Commit result
|
||||
|
||||
LLM->>MCP Client: tools/call (git push)
|
||||
MCP Client->>MCP Server: tools/call (git push)
|
||||
MCP Server->>Git System: git push
|
||||
Git System-->>MCP Server: push result
|
||||
MCP Server-->>MCP Client: CallToolResult (push)
|
||||
MCP Client-->>LLM: Push result
|
||||
|
||||
LLM->>User: "I've committed and pushed your changes!"
|
||||
```
|
||||
|
||||
### Code Review Prompts
|
||||
|
||||
> … a code review assistant … could offer a set of specialized prompts to help developers conduct more thorough and efficient code reviews.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as Client (e.g., IDE)
|
||||
participant S as Code Review Prompts MCP Server
|
||||
|
||||
C->>S: initialize
|
||||
S-->>C: InitializeResult (capabilities, etc.)
|
||||
C->>S: initialized
|
||||
C->>S: prompts/list
|
||||
S-->>C: ListPromptsResult (available prompts)
|
||||
|
||||
Note over C: User selects "security-review" prompt
|
||||
|
||||
C->>S: prompts/get (name: "security-review", arguments)
|
||||
S-->>C: GetPromptResult (messages for security review)
|
||||
|
||||
Note over C: User selects "performance-review" prompt
|
||||
|
||||
C->>S: prompts/get (name: "performance-review", arguments)
|
||||
S-->>C: GetPromptResult (messages for performance review)
|
||||
|
||||
Note over C: User selects "code-style-review" prompt
|
||||
|
||||
C->>S: prompts/get (name: "code-style-review", arguments)
|
||||
S-->>C: GetPromptResult (messages for style review)
|
||||
```
|
||||
|
||||
### GitHub PR Summaries Server
|
||||
|
||||
> an MCP server that summarizes GitHub pull requests
|
||||
>
|
||||
> …
|
||||
>
|
||||
>
|
||||
> 1. MCP server loads all the PRs on a GitHub repo
|
||||
> 2. MCP server requests LLM sampling to summarize each one
|
||||
> 3. The summaries are vended as MCP resources
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant MCP Server
|
||||
participant GitHub API
|
||||
participant LLM
|
||||
|
||||
Client->>MCP Server: initialize
|
||||
MCP Server->>Client: initialize_response
|
||||
Client->>MCP Server: initialized
|
||||
|
||||
MCP Server->>GitHub API: Fetch all PRs
|
||||
GitHub API->>MCP Server: PR details
|
||||
|
||||
loop For each PR
|
||||
MCP Server->>Client: sampling/createMessage (PR summary prompt)
|
||||
Client->>LLM: Sample
|
||||
LLM->>Client: Generated summary
|
||||
Client->>MCP Server: CreateMessageResult (PR summary)
|
||||
Note over MCP Server: Store summary as resource
|
||||
end
|
||||
|
||||
Note over Client: Some time later...
|
||||
|
||||
Client->>MCP Server: resources/list
|
||||
MCP Server->>Client: ListResourcesResult (PR summary URIs)
|
||||
|
||||
Client->>MCP Server: resources/read (PR summary URI)
|
||||
MCP Server->>Client: ReadResourceResult (PR summary)
|
||||
|
||||
Note over Client,MCP Server: Client can request more summaries as needed
|
||||
```
|
||||
Loading…
Reference in a new issue