https://github.com/SamMorrowDrums/mcp-go-starter
A starter repo for building a go MCP server
https://github.com/SamMorrowDrums/mcp-go-starter
Last synced: 2 months ago
JSON representation
A starter repo for building a go MCP server
- Host: GitHub
- URL: https://github.com/SamMorrowDrums/mcp-go-starter
- Owner: SamMorrowDrums
- License: mit
- Created: 2025-04-28T11:16:26.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-30T08:06:07.000Z (6 months ago)
- Last Synced: 2025-05-07T14:55:18.688Z (6 months ago)
- Language: Go
- Homepage:
- Size: 17.6 KB
- Stars: 0
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **mcp-go-starter** - A starter repo for building a go MCP server `go` `mcp` `server` `go install SamMorrowDrums/mcp-go-starter@latest` (⚙️ DevOps)
- awesome-mcp-servers - **mcp-go-starter** - A starter repo for building a go MCP server `go` `mcp` `server` `go install SamMorrowDrums/mcp-go-starter@latest` (⚙️ DevOps)
README
# mcp-go-starter
A starter repo for building a Go MCP server using [mcp-go](https://github.com/mark3labs/mcp-go), Cobra, and Viper.
## Quick Start
1. **Run the server from `/vscode/mcp.json`**
The server is configured to run out of the box, via the included mcp.json file.
2. **Run the server (development mode) using the script:**
```sh
./script/go-run
```
This script ensures you always run the latest code from the correct directory, just like the approach in [github/github-mcp-server#51](https://github.com/github/github-mcp-server/pull/51).
3. **Or build and run the server manually:**
```sh
go build -o mcp-server ./cmd/mcp && ./mcp-server stdio
```
## Environment Variables
- `MCP_GREETING`: Greeting to use for the hello tool and prompt (default: `Hello`)
- `MCP_SECRET`: Secret value for demonstration purposes (default: `Hello`)
## Features
- **Hello World Tool**: Takes a `name` argument and returns a greeting.
- **Markdown Resource**: Serves `pkg/example/resources/example.md` as an MCP resource.
- **Prompt Example**: Simple prompt that greets the user by name.
## Example: Calling the hello_world Tool
You can call the `hello_world` tool from your MCP client (such as VS Code with the MCP extension) or programmatically. Here’s an example using the tool with the argument `name: "Sam"`:
**Request:**
```json
{
"method": "call_tool",
"params": {
"tool": "hello_world",
"arguments": {
"name": "Sam"
}
},
"id": 1,
"jsonrpc": "2.0"
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"type": "text",
"text": "Hello, Sam!"
}
}
```
## Example: Calling the choose_color Tool (Enum)
**Request:**
```json
{
"method": "call_tool",
"params": {
"tool": "choose_color",
"arguments": {
"color": "green"
}
},
"id": 2,
"jsonrpc": "2.0"
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"type": "text",
"text": "You chose the color: green"
}
}
```
## Example: Getting a Prompt
**Request:**
```json
{
"method": "get_prompt",
"params": {
"prompt": "hello_prompt",
"arguments": {
"name": "Sam"
}
},
"id": 3,
"jsonrpc": "2.0"
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"title": "A friendly greeting",
"messages": [
{
"role": "assistant",
"content": {
"type": "text",
"text": "Hello, Sam! How can I help you today?"
}
}
]
}
}
```
## Example: Getting the Markdown Resource
**Request:**
```json
{
"method": "read_resource",
"params": {
"resource": "docs://example"
},
"id": 4,
"jsonrpc": "2.0"
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 4,
"result": [
{
"uri": "docs://example",
"mime_type": "text/markdown",
"text": "# Example Markdown Resource\n\nThis is an example markdown file served as an MCP resource.\n\n- You can edit this file to change the resource content.\n- It is embedded in the Go binary using Go's embed package.\n"
}
]
}
```
## Example: Prompt for an LLM Agent
If you want an LLM agent (such as Copilot or another MCP-compatible assistant) to call your tools and resources, you can use a prompt like this:
> You are an assistant with access to the following tools:
> - `hello_world`: Greets a person by name using the configured greeting.
> - `choose_color`: Lets you select a color from red, green, or blue.
> - `docs://example`: A markdown resource with example content.
>
> When a user asks for a greeting, call the `hello_world` tool with their name. If they ask to pick a color, call the `choose_color` tool with the color they want. If they ask for documentation or help, return the contents of the `docs://example` resource.
This prompt will encourage the LLM to use your tools and resources as intended.
## VS Code Integration
- `.vscode/mcp.json` is preconfigured for rapid development with environment variable inputs.
- Make sure to use the full path to the script in the `command` field for best results.
## Codespaces/Devcontainer
A basic devcontainer is provided for GitHub Codespaces with Go tools enabled.
---
For more details, see the [mcp-go README](https://github.com/mark3labs/mcp-go/blob/main/README.md).
## Additional Examples
### Raw JSON-RPC for Accessing Prompts
Note: Only some clients support prompts. Here's an example using direct JSON-RPC over stdio:
```bash
echo '{"jsonrpc":"2.0","id":3,"params":{"name": "hello_prompt"},"method":"prompts/get"}' | go run cmd/mcp/main.go stdio
```
Output:
```json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"description": "A friendly greeting",
"messages": [
{
"role": "assistant",
"content": {
"type": "text",
"text": "Hello, friend! How can I help you today?"
}
}
]
}
}
```