Add Model Context Protocol (MCP) support to Serpent

ThomasK33 · ThomasK33 · commit 70210af61849 · 2025-04-07T13:07:23.000+02:00
- Implement MCP server functionality in a new example application.
- Create README.md to document MCP usage, lifecycle, and methods.
- Develop main.go to define commands and expose them as MCP tools and resources.
- Introduce mcp.go to handle MCP server logic, including JSON-RPC request processing.
- Add tests for MCP server setup, command validation, and JSON schema generation.
- Update help template to display MCP tool and resource information.

Change-Id: I162ad9d8f1c8d4f5b5bdc37fefb1c99dce179bb2
Signed-off-by: Thomas Kosiewski &lt;tk@coder.com&gt;
diff --git a/command.go b/command.go
@@ -59,6 +59,16 @@ type Command struct {
 	Options     OptionSet
 	Annotations Annotations
 
+	// Tool is the name of the MCP tool this command provides.
+	// If set, the command can be invoked via MCP as a tool.
+	// Tool and Resource are mutually exclusive.
+	Tool string
+
+	// Resource is the URI of the MCP resource this command provides.
+	// If set, the command can be accessed via MCP as a resource.
+	// Tool and Resource are mutually exclusive.
+	Resource string
+
 	// Middleware is called before the Handler.
 	// Use Chain() to combine multiple middlewares.
 	Middleware  MiddlewareFunc
@@ -106,6 +116,11 @@ func (c *Command) init() error {
 	}
 	var merr error
 
+	// Validate that Tool and Resource are mutually exclusive
+	if c.Tool != "" && c.Resource != "" {
+		merr = errors.Join(merr, xerrors.Errorf("command %q cannot have both Tool and Resource set", c.Name()))
+	}
+
 	for i := range c.Options {
 		opt := &c.Options[i]
 		if opt.Name == "" {
@@ -558,6 +573,12 @@ func findArg(want string, args []string, fs *pflag.FlagSet) (int, error) {
 	return -1, xerrors.Errorf("arg %s not found", want)
 }
 
+// IsMCPEnabled returns true if the command is accessible via MCP
+// (has either Tool or Resource field set)
+func (c *Command) IsMCPEnabled() bool {
+	return c.Tool != "" || c.Resource != ""
+}
+
 // Run executes the command.
 // If two command share a flag name, the first command wins.
 //
diff --git a/example/mcp/README.md b/example/mcp/README.md
@@ -0,0 +1,167 @@
+# Serpent MCP Server Example
+
+This example demonstrates how to use the Model Context Protocol (MCP) functionality in Serpent to create a command-line tool that can also be used as an MCP server.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a protocol for communication between AI models and external tools or resources. It allows AI models to invoke tools and access resources provided by MCP servers.
+
+## How to Use
+
+### Running as a CLI Tool
+
+You can run the example as a normal CLI tool:
+
+```bash
+# Echo a message
+go run main.go echo "Hello, World!"
+
+# Get version information
+go run main.go version
+
+# Show help
+go run main.go --help
+```
+
+### Running as an MCP Server
+
+You can run the example as an MCP server using the `mcp` subcommand:
+
+```bash
+go run main.go mcp
+```
+
+This will start an MCP server that listens on stdin/stdout for JSON-RPC 2.0 requests.
+
+## MCP Protocol
+
+### Lifecycle
+
+The MCP server follows the standard MCP lifecycle:
+
+1. The client sends an `initialize` request to the server
+2. The server responds with its capabilities
+3. The client sends an `initialized` notification
+4. After this, normal message exchange can begin
+
+All MCP methods will return an error if called before the initialization process is complete.
+
+### Methods
+
+The MCP server implements the following JSON-RPC 2.0 methods:
+
+- `initialize`: Initializes the MCP server and returns its capabilities
+- `notifications/initialized`: Notifies the server that initialization is complete
+- `ping`: Simple ping method to check server availability
+- `tools/list`: Lists all available tools
+- `tools/call`: Invokes a tool with the given arguments
+- `resources/list`: Lists all available resources
+- `resources/templates/list`: Lists all available resource templates
+- `resources/read`: Accesses a resource with the given URI
+
+### Example Requests
+
+Here are some example JSON-RPC 2.0 requests you can send to the MCP server:
+
+#### Initialize
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"manual-test-client","version":"1.0.0"},"capabilities":{}}}
+```
+
+Response:
+```json
+{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":true,"resources":true}}}
+```
+
+#### Initialized
+
+```json
+{"jsonrpc":"2.0","id":2,"method":"notifications/initialized"}
+```
+
+#### List Tools
+
+```json
+{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}
+```
+
+#### List Resources
+
+```json
+{"jsonrpc":"2.0","id":4,"method":"resources/list","params":{}}
+```
+
+#### Invoke Tool
+
+```json
+{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"echo","arguments":{"_":"Hello from MCP!"}}}
+```
+
+#### Access Resource
+
+```json
+{"jsonrpc":"2.0","id":6,"method":"resources/read","params":{"uri":"version"}}
+```
+
+### Complete Initialization Example
+
+Here's a complete example of the initialization process:
+
+```json
+// Client sends initialize request
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"manual-test-client","version":"1.0.0"},"capabilities":{}}}
+
+// Server responds with capabilities
+{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":true,"resources":true}}}
+
+// Client sends initialized notification
+{"jsonrpc":"2.0","id":2,"method":"notifications/initialized"}
+
+// Server acknowledges (optional, since initialized is technically a notification)
+{"jsonrpc":"2.0","id":2,"result":{}}
+
+// Now client can use MCP methods
+{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}
+```
+
+## How to Implement MCP in Your Own Commands
+
+To implement MCP in your own Serpent commands:
+
+1. Add the `Tool` field to commands that should be invokable as MCP tools
+2. Add the `Resource` field to commands that should be accessible as MCP resources
+3. Add the MCP command to your root command using `root.AddMCPCommand()`
+
+Example:
+
+```go
+// Create a command that will be exposed as an MCP tool
+echoCmd := &serpent.Command{
+    Use:   "echo [message]",
+    Short: "Echo a message",
+    Tool:  "echo", // This makes the command available as an MCP tool
+    Handler: func(inv *serpent.Invocation) error {
+        // Command implementation
+    },
+}
+
+// Create a command that will be exposed as an MCP resource
+versionCmd := &serpent.Command{
+    Use:      "version",
+    Short:    "Get version information",
+    Resource: "version", // This makes the command available as an MCP resource
+    Handler: func(inv *serpent.Invocation) error {
+        // Command implementation
+    },
+}
+
+// Add the MCP command to the root command
+root.AddSubcommands(serpent.MCPCommand())
+```
+
+## Notes
+
+- A command can have either a `Tool` field or a `Resource` field, but not both
+- Commands with neither `Tool` nor `Resource` set will not be accessible via MCP
+- The MCP server communicates using JSON-RPC 2.0 over stdin/stdout
diff --git a/example/mcp/main.go b/example/mcp/main.go
@@ -0,0 +1,87 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/coder/serpent"
+)
+
+func main() {
+	// Create a root command
+	root := &serpent.Command{
+		Use:   "mcp-example",
+		Short: "Example MCP server",
+		Long:  "An example of how to use the MCP functionality in serpent.",
+	}
+
+	var repeats int64 = 2
+
+	// Add a command that will be exposed as an MCP tool
+	echoCmd := &serpent.Command{
+		Use:   "echo [message]",
+		Short: "Echo a message",
+		Tool:  "echo", // This makes the command available as an MCP tool
+		Options: []serpent.Option{
+			{
+				Name:        "repeat",
+				Flag:        "repeat", // Add the Flag field so it's exposed in JSON Schema
+				Description: "Number of times to repeat the message.",
+				Default:     "2",
+				Value:       serpent.Int64Of(&repeats),
+			},
+		},
+		Handler: func(inv *serpent.Invocation) error {
+			message := "Hello, World!"
+			if len(inv.Args) > 0 {
+				message = strings.Join(inv.Args, " ")
+			}
+			for i := int64(0); i < repeats; i++ {
+				if _, err := fmt.Fprintln(inv.Stdout, message); err != nil {
+					return err
+				}
+			}
+			return nil
+		},
+	}
+	root.AddSubcommands(echoCmd)
+
+	// Add a command that will be exposed as an MCP resource
+	versionCmd := &serpent.Command{
+		Use:      "version",
+		Short:    "Get version information",
+		Resource: "version", // This makes the command available as an MCP resource
+		Handler: func(inv *serpent.Invocation) error {
+			version := map[string]string{
+				"version": "1.0.0",
+				"name":    "serpent-mcp-example",
+				"author":  "Coder",
+			}
+			encoder := json.NewEncoder(inv.Stdout)
+			return encoder.Encode(version)
+		},
+	}
+	root.AddSubcommands(versionCmd)
+
+	// Add a command that will not be exposed via MCP
+	hiddenCmd := &serpent.Command{
+		Use:   "hidden",
+		Short: "This command is not exposed via MCP",
+		Handler: func(inv *serpent.Invocation) error {
+			_, err := fmt.Fprintln(inv.Stdout, "This command is not exposed via MCP")
+			return err
+		},
+	}
+	root.AddSubcommands(hiddenCmd)
+
+	// Add the MCP command to the root command
+	root.AddSubcommands(serpent.MCPCommand())
+
+	// Run the command
+	if err := root.Invoke(os.Args[1:]...).WithOS().Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
diff --git a/help.tpl b/help.tpl
@@ -17,6 +17,14 @@
 {{"  Aliases: "}} {{- joinStrings .}}
 {{- end }}
 
+{{ with .Tool }}
+{{"  MCP Tool: "}} {{- . }}
+{{- end }}
+
+{{ with .Resource }}
+{{"  MCP Resource: "}} {{- . }}
+{{- end }}
+
 {{- with .Long}}
 {{"\n"}}
 {{- indent . 2}}
diff --git a/mcp.go b/mcp.go
diff --git a/mcp_test.go b/mcp_test.go
