Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
a019b7e
[Copilot Dreaming] Return registrable tools from SDK migrations
Copilot Nov 12, 2026
7676f72
[Copilot Dreaming] Distinguish schema components from constructor res…
Copilot Nov 12, 2026
ed25d27
[Copilot Dreaming] Use the supported JSON default in migration examples
Copilot Nov 12, 2026
5c568a1
[Copilot Dreaming] Remove the prediction that every migration breaks …
Copilot Nov 12, 2026
9c0c529
[Copilot Dreaming] Remove argument ordering as a required snapshot ch…
Copilot Nov 12, 2026
77a1159
[Copilot Dreaming] Remove the misleading repository-size shortcut
Copilot Nov 12, 2026
f6e4e03
[Copilot Dreaming] Make the focused unit-test example select a real test
Copilot Nov 12, 2026
72db01b
[Copilot Dreaming] Point toolset exploration at its existing package
Copilot Nov 12, 2026
cf7fb34
[Copilot Dreaming] Match ignore guidance to the configured filename p…
Copilot Nov 12, 2026
8ecde48
[Copilot Dreaming] Remove the repeated catalogue lint mandate
Copilot Nov 12, 2026
fc38e1f
[Copilot Dreaming] Remove the repeated catalogue documentation mandate
Copilot Nov 12, 2026
5be8ccb
[Copilot Dreaming] Remove the blanket workflow-trigger assertion
Copilot Nov 12, 2026
a71cbe8
[Copilot Dreaming] Match documented lint setup to configured CI
Copilot Nov 12, 2026
fb62d59
[Copilot Dreaming] Identify the actual release trigger
Copilot Nov 12, 2026
567c4cd
[Copilot Dreaming] Remove the categorical exclusion of external test …
Copilot Nov 12, 2026
3c5977f
[Copilot Dreaming] Use the repository REST mocking helper
Copilot Nov 12, 2026
f41418d
[Copilot Dreaming] Remove the repeated wide-audience clarity rule
Copilot Nov 12, 2026
6ede3c7
[Copilot Dreaming] Remove the repeated atomic-commit rule
Copilot Nov 12, 2026
aa2d75f
[Copilot Dreaming] Remove the repeated structure-protection rule
Copilot Nov 12, 2026
c0c8f19
[Copilot Dreaming] Remove the repeated comment-restraint rule
Copilot Nov 12, 2026
c349601
[Copilot Dreaming] Remove the repeated library-export rule
Copilot Nov 12, 2026
7593fc4
[Copilot Dreaming] Register new tools at the existing registry
Copilot Nov 12, 2026
e79d948
[Copilot Dreaming] Document PAT authentication without making it mand…
Copilot Nov 12, 2026
b893875
[Copilot Dreaming] Remove the false default-stdio qualifier
Copilot Nov 12, 2026
d89361e
[Copilot Dreaming] Remove the repeated local-server priority reminder
Copilot Nov 12, 2026
36f7cc6
[Copilot Dreaming] Remove the repeated export sentence from the remot…
Copilot Nov 12, 2026
fa238bf
[Copilot Dreaming] Remove the repeated pre-commit lint reminder
Copilot Nov 12, 2026
a59dbf7
[Copilot Dreaming] Remove the repeated schema-snapshot reminder
Copilot Nov 12, 2026
928c667
[Copilot Dreaming] Remove the repeated generated-documentation reminder
Copilot Nov 12, 2026
9dbdef5
[Copilot Dreaming] Remove the repeated live-test prerequisite reminder
Copilot Nov 12, 2026
873d48e
[Copilot Dreaming] Remove the repeated testing-utility priority reminder
Copilot Nov 12, 2026
b233692
[Copilot Dreaming] Keep the remaining reminder sequence readable
Copilot Nov 12, 2026
3325166
[Copilot Dreaming] Recover mcpcurl commands blocked by unrelated schemas
Copilot Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .github/agents/go-sdk-tool-migrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ When generating the migration guide, consider the following aspects:

* 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 return type for the tool constructor function should be updated from `mcp.Tool, server.ToolHandlerFunc` to `inventory.ServerTool`.
* 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.
Expand Down Expand Up @@ -60,11 +60,11 @@ return mcp.NewTool(
...
```

The corresponding input schema in modelcontextprotocol/go-sdk would look like this:
The `mcp.Tool` component of the migrated `inventory.ServerTool` would look like this:

```go
...
return mcp.Tool{
mcp.Tool{
Name: "list_dependabot_alerts",
Description: t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository."),
Annotations: &mcp.ToolAnnotations{
Expand All @@ -86,7 +86,7 @@ return mcp.Tool{
Type: "string",
Description: "Filter dependabot alerts by state. Defaults to open",
Enum: []any{"open", "fixed", "dismissed", "auto_dismissed"},
Default: "open",
Default: json.RawMessage(`"open"`),
},
"severity": {
Type: "string",
Expand All @@ -103,10 +103,10 @@ return mcp.Tool{

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.:
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.
You should however, only update the toolsnaps after confirming that the schema changes are intentional and correct. Some schema changes are unavoidable, however the schemas themselves should remain logically equivalent.
52 changes: 20 additions & 32 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ This is the **GitHub MCP Server**, a Model Context Protocol (MCP) server that co
- **Primary Package:** github-mcp-server (stdio MCP server - **this is the main focus**)
- **Secondary Package:** mcpcurl (testing utility - don't break it, but not the priority)
- **Framework:** Uses modelcontextprotocol/go-sdk for MCP protocol, google/go-github for GitHub API
- **Size:** ~60MB repository, 70 Go files
- **Library Usage:** This repository is also used as a library by the remote server. Functions that could be called by other repositories should be exported (capitalized), even if not required internally. Preserve existing export patterns.

**Code Quality Standards:**
Expand Down Expand Up @@ -56,7 +55,7 @@ go build -v ./cmd/github-mcp-server
go test ./pkg/github -v

# Run specific test
go test ./pkg/github -run TestGetMe
go test ./pkg/github -run Test_GetMe
```

## Project Structure
Expand All @@ -71,7 +70,7 @@ go test ./pkg/github -run TestGetMe
├── pkg/ # Public API packages
│ ├── github/ # GitHub API MCP tools implementation
│ │ └── __toolsnaps__/ # Tool schema snapshots (*.snap files)
│ ├── toolsets/ # Toolset configuration & management
│ ├── inventory/ # Toolset configuration & management
│ ├── errors/ # Error handling utilities
│ ├── sanitize/ # HTML/content sanitization
│ ├── log/ # Logging utilities
Expand All @@ -97,13 +96,13 @@ go test ./pkg/github -run TestGetMe
- **Dockerfile:** Multi-stage build (golang:1.27.3-alpine → distroless)
- **server.json:** MCP server metadata for registry
- **.goreleaser.yaml:** Release automation config
- **.gitignore:** Excludes bin/, dist/, vendor/, *.DS_Store, github-mcp-server binary
- **.gitignore:** Excludes bin/, dist/, vendor/, .DS_Store, github-mcp-server binary

### Important Scripts (script/ directory)

- **script/lint** - Runs `gofmt` + `golangci-lint`. **MUST RUN** before committing
- **script/lint** - Runs `gofmt` + `golangci-lint`.
- **script/test** - Runs `go test -race ./...` (full test suite)
- **script/generate-docs** - Updates README.md tool documentation. Run after tool changes
- **script/generate-docs** - Updates README.md tool documentation.
- **script/licenses** - Updates third-party license files when dependencies change
- **script/licenses-check** - Validates license compliance (runs in CI)
- **script/get-me** - Quick test script for get_me tool
Expand All @@ -112,15 +111,15 @@ go test ./pkg/github -run TestGetMe

## GitHub Workflows (CI/CD)

All workflows run on push/PR unless noted. Located in `.github/workflows/`:
Located in `.github/workflows/`:

1. **go.yml** - Build and test on ubuntu/windows/macos. Runs `script/test` and builds binary
2. **lint.yml** - Runs golangci-lint-action v2.5 (GitHub Action) with actions/setup-go stable
2. **lint.yml** - Runs golangci-lint-action v9 (GitHub Action) with actions/setup-go reading `go.mod`
3. **docs-check.yml** - Verifies README.md is up-to-date by running generate-docs and checking git diff
4. **code-scanning.yml** - CodeQL security analysis for Go and GitHub Actions
5. **license-check.yml** - Runs `script/licenses-check` to validate compliance
6. **docker-publish.yml** - Publishes container image to ghcr.io
7. **goreleaser.yml** - Creates releases (main branch only)
7. **goreleaser.yml** - Creates releases (version tags)
8. **registry-releaser.yml** - Updates MCP registry

**All of these must pass for PR merge.** If docs-check fails, run `script/generate-docs` and commit changes.
Expand All @@ -130,8 +129,8 @@ All workflows run on push/PR unless noted. Located in `.github/workflows/`:
### Unit Tests

- Use `testify` for assertions (`require` for critical checks, `assert` for non-blocking)
- Tests are in `*_test.go` files alongside implementation (internal tests, not `_test` package)
- Mock GitHub API with `go-github-mock` (REST) or `githubv4mock` (GraphQL)
- Tests are in `*_test.go` files alongside implementation
- Mock GitHub API with `MockHTTPClientWithHandlers` (REST) or `githubv4mock` (GraphQL)
- Test structure for tools:
1. Test tool snapshot
2. Verify critical schema properties (e.g., ReadOnly annotation)
Expand Down Expand Up @@ -174,21 +173,16 @@ All workflows run on push/PR unless noted. Located in `.github/workflows/`:
### Code Patterns

- **Keep changes minimal and focused** on the specific issue being addressed
- **Prefer clarity over cleverness** - code must be understandable by a wide audience
- **Atomic commits** - each commit should be a complete, logical change
- **Maintain or improve structure** - never degrade code organization
- Use table-driven tests for behavioral testing
- Comment sparingly - code should be self-documenting
- Follow standard Go conventions (Effective Go, Go proverbs)
- **Test changes thoroughly** before committing
- Export functions (capitalize) if they could be used by other repos as a library

## Common Development Workflows

### Adding a New MCP Tool

1. Add tool implementation in `pkg/github/` (e.g., `foo_tools.go`)
2. Register tool in appropriate toolset in `pkg/github/` or `pkg/toolsets/`
2. Register tool in appropriate toolset in `pkg/github/tools.go`
3. Write unit tests following the tool test pattern
4. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot
5. Run `script/generate-docs` to update README
Expand Down Expand Up @@ -239,7 +233,7 @@ All workflows run on push/PR unless noted. Located in `.github/workflows/`:

## Environment Variables

- **GITHUB_PERSONAL_ACCESS_TOKEN** - Required for server operation and e2e tests
- **GITHUB_PERSONAL_ACCESS_TOKEN** - Optional PAT authentication for the stdio server; OAuth and GitHub App authentication are alternatives.
- **GITHUB_HOST** - For GitHub Enterprise Server (prefix with `https://`)
- **GITHUB_TOOLSETS** - Comma-separated toolset list (overrides --toolsets flag)
- **GITHUB_READ_ONLY** - Set to "1" for read-only mode
Expand Down Expand Up @@ -270,22 +264,16 @@ server.json - MCP server registry metadata
### Main Entry Point

`cmd/github-mcp-server/main.go` - Uses cobra for CLI, viper for config, supports:
- `stdio` command (default) - MCP stdio transport
- `stdio` command - MCP stdio transport
- `generate-docs` command - Documentation generation
- Flags: --toolsets, --read-only, --gh-host, --log-file

## Important Reminders

1. **PRIMARY FOCUS:** The local stdio MCP server (github-mcp-server) - this is what you should work on and test with
2. **REMOTE SERVER:** Ignore remote server instructions when making code changes (unless specifically asked). This repo is used as a library by the remote server, so keep functions exported (capitalized) if they could be called by other repos, even if not needed internally.
3. **ALWAYS** trust these instructions first - only search if information is incomplete or incorrect
4. **NEVER** use `script/tag-release` or push tags
5. **NEVER** skip `script/lint` before committing Go code changes
6. **ALWAYS** update toolsnaps when changing MCP tool schemas
7. **ALWAYS** run `script/generate-docs` after modifying tools
8. For specific test files, use `go test ./path -run TestName` not full suite
9. E2E tests require PAT token - you likely cannot run them
10. Toolsnaps are API documentation - treat changes seriously
11. Build/test/lint are very fast (~1s each) - run frequently
12. CI failures for docs-check or license-check have simple fixes (run the script)
13. mcpcurl is secondary - don't break it, but it's not the priority
1. **REMOTE SERVER:** Ignore remote server instructions when making code changes (unless specifically asked).
2. **ALWAYS** trust these instructions first - only search if information is incomplete or incorrect
3. **NEVER** use `script/tag-release` or push tags
4. For specific test files, use `go test ./path -run TestName` not full suite
5. Toolsnaps are API documentation - treat changes seriously
6. Build/test/lint are very fast (~1s each) - run frequently
7. CI failures for docs-check or license-check have simple fixes (run the script)
4 changes: 3 additions & 1 deletion cmd/mcpcurl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,9 @@ Use one of the tools:

## Dynamic Commands

All tools provided by the MCP server are automatically available as subcommands under the `tools` command. Each generated command has:
To recover a missing `mcpcurl` subcommand blocked by another tool's schema, replace `--toolsets=<set>` with `--tools=<tool>` in the `--stdio-server-cmd` server command.

Each generated command has:

- Appropriate flags matching the tool's input schema
- Validation for required parameters
Expand Down
Loading