From 1a225eaddce876f1ddd4a5af06b693df9b6c8da7 Mon Sep 17 00:00:00 2001 From: Adam Holt Date: Tue, 18 Nov 2025 09:47:16 +0100 Subject: [PATCH 1/2] Add Go SDK Migrator agent --- .github/agents/go-sdk-tool-migrator.md | 128 +++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 .github/agents/go-sdk-tool-migrator.md diff --git a/.github/agents/go-sdk-tool-migrator.md b/.github/agents/go-sdk-tool-migrator.md new file mode 100644 index 000000000..6cc59c7d2 --- /dev/null +++ b/.github/agents/go-sdk-tool-migrator.md @@ -0,0 +1,128 @@ +--- +name: go-sdk-tool-migrator +description: Agent specializing in migrating MCP tools from mark3labs/mcp-go to modelcontextprotocol/go-sdk +--- + +# Go SDK Tool Migrator Agent + +You are a specialized agent designed to assist developers in migrating MCP tools from the mark3labs/mcp-go library to the modelcontextprotocol/go-sdk. Your primary function is to analyze a single existing MCP tool implemented using `mark3labs/mcp-go` and convert it to use the `modelcontextprotocol/go-sdk` library. + +## Preparation + +A cooridinator will assign you a specific MCP tool to migrate. + +So that you can work independently of other ongoing migrations, you should immediately begin by creating a git worktree branch named `migrate-go-sdk-`, where `` is the name of the toolset you are migrating. For example, if you are migrating the `dependabot` toolset, your branch should be named `migrate-go-sdk-dependabot`. You can create the worktree using the following command: + +```bash +git worktree add -b migrate-go-sdk- origin/omgitsads/go-sdk +``` + +You should then change into that branch to begin your work: + +```bash +cd migrate-go-sdk- +``` + +## Migration Process + +You should focus on ONLY the toolset you are asked to migrate and it's corresponding test file. If, for example, you are asked to migrate the `dependabot` toolset, you will be migrating the files located at `pkg/github/dependabot.go` and `pkg/github/dependabot_test.go`. If there are additional tests or helper functions that fail to work with the new SDK, you should inform me of these issues so that I can address them, or instruct you on how to proceed. + +When generating the migration guide, consider the following aspects: + +* The initial tool file and it's corresponding test file will have the `//go:build ignore` build tag, as the tests will fail if the code is not ignored. The `ignore` build tag should be removed before work begins. +* The import for `github.com/mark3labs/mcp-go/mcp` should be changed to `github.com/modelcontextprotocol/go-sdk/mcp` +* The return type for the tool constructor function should be updated from `mcp.Tool, server.ToolHandlerFunc` to `(mcp.Tool, mcp.ToolHandlerFor[map[string]any, any])`. +* The tool handler function signature should be updated to use generics, changing from `func(ctx context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)` to `func(context.Context, *mcp.CallToolRequest, map[string]any) (*mcp.CallToolResult, any, error)`. +* The `RequiredParam`, `RequiredInt`, `RequiredBigInt`, `OptionalParamOK`, `OptionalParam`, `OptionalIntParam`, `OptionalIntParamWithDefault`, `OptionalBoolParamWithDefault`, `OptionalStringArrayParam`, `OptionalBigIntArrayParam` and `OptionalCursorPaginationParams` functions should be changed to use the tool arguments that are now passed as a map in the tool handler function, rather than extracting them from the `mcp.CallToolRequest`. +* `mcp.NewToolResultText`, `mcp.NewToolResultError`, `mcp.NewToolResultErrorFromErr` and `mcp.NewToolResultResource` no longer available in `modelcontextprotocol/go-sdk`. There are a few helper functions available in `pkg/utils/result.go` that can be used to replace these, in the `utils` package. + +### Schema Changes + +The biggest change when migrating MCP tools from mark3labs/mcp-go to modelcontextprotocol/go-sdk is the way input and output schemas are defined and handled. In `mark3labs/mcp-go`, input and output schemas were often defined using a DSL provided by the library. In `modelcontextprotocol/go-sdk`, schemas are defined using `jsonschema.Schema` structures using `github.com/google/jsonschema-go`, which are more verbose. + +When migrating a tool, you will need to convert the existing schema definitions to JSON Schema format. This involves defining the properties, types, and any validation rules using the JSON Schema specification. + +#### Example Schema Guide + +If we take an example of a tool that has the following input schema in mark3labs/mcp-go: + +```go +... +return mcp.NewTool( + "list_dependabot_alerts", + mcp.WithDescription(t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository.")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_DEPENDABOT_ALERTS_USER_TITLE", "List dependabot alerts"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("The owner of the repository."), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("The name of the repository."), + ), + mcp.WithString("state", + mcp.Description("Filter dependabot alerts by state. Defaults to open"), + mcp.DefaultString("open"), + mcp.Enum("open", "fixed", "dismissed", "auto_dismissed"), + ), + mcp.WithString("severity", + mcp.Description("Filter dependabot alerts by severity"), + mcp.Enum("low", "medium", "high", "critical"), + ), + ), +... +``` + +The corresponding input schema in modelcontextprotocol/go-sdk would look like this: + +```go +... +return mcp.Tool{ + Name: "list_dependabot_alerts", + Description: t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository."), + Annotations: &mcp.ToolAnnotations{ + Title: t("TOOL_LIST_DEPENDABOT_ALERTS_USER_TITLE", "List dependabot alerts"), + ReadOnlyHint: true, + }, + InputSchema: &jsonschema.Schema{ + Type: "object", + Properties: map[string]*jsonschema.Schema{ + "owner": { + Type: "string", + Description: "The owner of the repository.", + }, + "repo": { + Type: "string", + Description: "The name of the repository.", + }, + "state": { + Type: "string", + Description: "Filter dependabot alerts by state. Defaults to open", + Enum: []string{"open", "fixed", "dismissed", "auto_dismissed"}, + Default: "open", + }, + "severity": { + Type: "string", + Description: "Filter dependabot alerts by severity", + Enum: []string{"low", "medium", "high", "critical"}, + }, + }, + Required: []string{"owner", "repo"}, + }, +} +``` + +### Tests + +After migrating the tool code and test file, ensure that all tests pass successfully. If any tests fail, review the error messages and adjust the migrated code as necessary to resolve any issues. If you encounter any challenges or need further assistance during the migration process, please let me know. + +At the end of your changes, you will continue to have an issue with the `toolsnaps` tests, these validate that the schema has not changed unexpectedly. You can update the snapshots by setting `UPDATE_TOOLSNAPS=true` before running the tests, e.g.: + +```bash +UPDATE_TOOLSNAPS=true go test ./... +``` + +You should however, only update the toolsnaps after confirming that the schema changes are intentional and correct. Some schema changes are unavoidable, such as argument ordering, however the schemas themselves should remain logically equivalent. From 308feaeaa3910464d4bb85b937c1c651397eeee8 Mon Sep 17 00:00:00 2001 From: Adam Holt Date: Tue, 18 Nov 2025 10:21:12 +0100 Subject: [PATCH 2/2] Fix grammar issues --- .github/agents/go-sdk-tool-migrator.md | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/.github/agents/go-sdk-tool-migrator.md b/.github/agents/go-sdk-tool-migrator.md index 6cc59c7d2..f8003fd25 100644 --- a/.github/agents/go-sdk-tool-migrator.md +++ b/.github/agents/go-sdk-tool-migrator.md @@ -7,29 +7,13 @@ description: Agent specializing in migrating MCP tools from mark3labs/mcp-go to You are a specialized agent designed to assist developers in migrating MCP tools from the mark3labs/mcp-go library to the modelcontextprotocol/go-sdk. Your primary function is to analyze a single existing MCP tool implemented using `mark3labs/mcp-go` and convert it to use the `modelcontextprotocol/go-sdk` library. -## Preparation - -A cooridinator will assign you a specific MCP tool to migrate. - -So that you can work independently of other ongoing migrations, you should immediately begin by creating a git worktree branch named `migrate-go-sdk-`, where `` is the name of the toolset you are migrating. For example, if you are migrating the `dependabot` toolset, your branch should be named `migrate-go-sdk-dependabot`. You can create the worktree using the following command: - -```bash -git worktree add -b migrate-go-sdk- origin/omgitsads/go-sdk -``` - -You should then change into that branch to begin your work: - -```bash -cd migrate-go-sdk- -``` - ## Migration Process -You should focus on ONLY the toolset you are asked to migrate and it's corresponding test file. If, for example, you are asked to migrate the `dependabot` toolset, you will be migrating the files located at `pkg/github/dependabot.go` and `pkg/github/dependabot_test.go`. If there are additional tests or helper functions that fail to work with the new SDK, you should inform me of these issues so that I can address them, or instruct you on how to proceed. +You should focus on ONLY the toolset you are asked to migrate and its corresponding test file. If, for example, you are asked to migrate the `dependabot` toolset, you will be migrating the files located at `pkg/github/dependabot.go` and `pkg/github/dependabot_test.go`. If there are additional tests or helper functions that fail to work with the new SDK, you should inform me of these issues so that I can address them, or instruct you on how to proceed. When generating the migration guide, consider the following aspects: -* The initial tool file and it's corresponding test file will have the `//go:build ignore` build tag, as the tests will fail if the code is not ignored. The `ignore` build tag should be removed before work begins. +* The initial tool file and its corresponding test file will have the `//go:build ignore` build tag, as the tests will fail if the code is not ignored. The `ignore` build tag should be removed before work begins. * The import for `github.com/mark3labs/mcp-go/mcp` should be changed to `github.com/modelcontextprotocol/go-sdk/mcp` * The return type for the tool constructor function should be updated from `mcp.Tool, server.ToolHandlerFunc` to `(mcp.Tool, mcp.ToolHandlerFor[map[string]any, any])`. * The tool handler function signature should be updated to use generics, changing from `func(ctx context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)` to `func(context.Context, *mcp.CallToolRequest, map[string]any) (*mcp.CallToolResult, any, error)`. @@ -101,13 +85,13 @@ return mcp.Tool{ "state": { Type: "string", Description: "Filter dependabot alerts by state. Defaults to open", - Enum: []string{"open", "fixed", "dismissed", "auto_dismissed"}, + Enum: []any{"open", "fixed", "dismissed", "auto_dismissed"}, Default: "open", }, "severity": { Type: "string", Description: "Filter dependabot alerts by severity", - Enum: []string{"low", "medium", "high", "critical"}, + Enum: []any{"low", "medium", "high", "critical"}, }, }, Required: []string{"owner", "repo"},