Skip to content

Commit

Permalink
Merge pull request #2 from wesen/task/add-config-file-profiles
Browse files Browse the repository at this point in the history 
Add configuration file support and fix SSE notifications
  • Loading branch information
@wesen
wesen authored Feb 11, 2025
2 parents 36d12b6 + 6c11296 commit 898ec14
Show file tree
Hide file tree
Showing 43 changed files with 3,605 additions and 1,709 deletions.
86 changes: 1 addition & 85 deletions .vscode/launch.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,91 +17,7 @@
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/go-go-mcp",
"args": ["start", "--transport", "sse", "--repositories", "examples/prompto", "--log-level", "debug", "--port", "3000"],
"cwd": "${workspaceFolder}"
},
{
"name": "Simplify HTML",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/tools/simplify-html",
"args": ["simplify", "--files", "/tmp/foxp3.html", "--max-list-items", "5"],
"cwd": "${workspaceFolder}"
},
{
"name": "Test HTML Selector",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/tools/test-html-selector",
"args": [
"select",
"--config",
"cmd/tools/test-html-selector/examples/tutorial/01-basic-text.yaml",
"--files",
"cmd/tools/test-html-selector/examples/tutorial/01-basic-text.html"
],
"cwd": "${workspaceFolder}"
},
{
"name": "Test HTML Selector - PubMed FOXP3",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/tools/test-html-selector",
"args": [
"select",
"--config",
"cmd/tools/test-html-selector/examples/pubmed.yaml",
"--urls",
"https://pubmed.ncbi.nlm.nih.gov/?term=foxp3",
"--extract"
],
"cwd": "${workspaceFolder}"
},
{
"name": "Run HTML Extract - HN",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/go-go-mcp",
"args": ["run-command", "examples/html-extract/fetch-html.yaml", "--urls", "https://news.ycombinator.com/"],
"cwd": "${workspaceFolder}"
},
{
"name": "HTML Selector - CSS Select",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/tools/test-html-selector",
"args": [
"select",
"--files",
"hn.html",
"--log-level",
"DEBUG",
"--select-css",
"td.title"
],
"cwd": "${workspaceFolder}"
},
{
"name": "HTML Selector - Config File",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/tools/test-html-selector",
"args": [
"select",
"--files",
"hn.html",
"--log-level",
"DEBUG",
"--show-simplified",
"--config",
"/tmp/html-extraction-2025-01-26-18-20-00.yaml"
],
"args": ["start", "--transport", "sse", "--profile", "all", "--log-level", "debug", "--port", "3000"],
"cwd": "${workspaceFolder}"
}
]
Expand Down
1 change: 1 addition & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ bump-glazed:
go get github.com/go-go-golems/glazed@latest
go get github.com/go-go-golems/clay@latest
go get github.com/go-go-golems/geppetto@latest
go get github.com/go-go-golems/parka@latest
go mod tidy

go-go-mcp_BINARY=$(shell which go-go-mcp)
Expand Down
208 changes: 176 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,44 @@

A Go implementation of the Model Context Protocol (MCP), providing a framework for building MCP servers and clients.

### Installation

To install the `go-go-mcp` command line tool with homebrew, run:

```bash
brew tap go-go-golems/go-go-go
brew install go-go-golems/go-go-go/go-go-mcp
```

To install the `go-go-mcp` command using apt-get, run:

```bash
echo "deb [trusted=yes] https://apt.fury.io/go-go-golems/ /" >> /etc/apt/sources.list.d/fury.list
apt-get update
apt-get install go-go-mcp
```

To install using `yum`, run:

```bash
echo "
[fury]
name=Gemfury Private Repo
baseurl=https://yum.fury.io/go-go-golems/
enabled=1
gpgcheck=0
" >> /etc/yum.repos.d/fury.repo
yum install go-go-mcp
```

To install using `go get`, run:

```bash
go get -u github.com/go-go-golems/go-go-mcp/cmd/go-go-mcp
```

Finally, install by downloading the binaries straight from [github](https://github.com/go-go-golems/go-go-mcp/releases).

## Overview

This project implements the [Model Context Protocol](https://github.com/modelcontextprotocol/specification), which enables standardized communication between AI applications and language models. The implementation includes:
Expand Down Expand Up @@ -154,10 +192,10 @@ Start the server with either stdio or SSE transport:

```bash
# Start with stdio transport (default)
./go-go-mcp start --transport stdio
go-go-mcp start --transport stdio

# Start with SSE transport
./go-go-mcp start --transport sse --port 3001
go-go-mcp start --transport sse --port 3001
```

#### Client Mode
Expand All @@ -166,26 +204,26 @@ Use the client subcommand to interact with an MCP server:

```bash
# List available prompts (uses default server: go-go-mcp start --transport stdio)
./go-go-mcp client prompts list
go-go-mcp client prompts list

# List available tools
./go-go-mcp client tools list
go-go-mcp client tools list

# Execute a prompt with arguments
./go-go-mcp client prompts execute hello --args '{"name":"World"}'
go-go-mcp client prompts execute hello --args '{"name":"World"}'

# Call a tool with arguments
./go-go-mcp client tools call echo --args '{"message":"Hello, MCP!"}'
go-go-mcp client tools call echo --args '{"message":"Hello, MCP!"}'
```

You can customize the server command and arguments if needed:

```bash
# Use a different server binary with custom arguments
./go-go-mcp client --command custom-server,start,--debug,--port,8001 prompts list
go-go-mcp client --command custom-server,start,--debug,--port,8001 prompts list

# Use a server with a specific configuration
./go-go-mcp client -c go-go-mcp,start,--config,config.yaml prompts list
go-go-mcp client -c go-go-mcp,start,--config,config.yaml prompts list
```

#### Using SSE Transport
Expand All @@ -194,52 +232,158 @@ For web-based applications, use the SSE transport:

```bash
# Start the server with SSE transport
./go-go-mcp start --transport sse --port 3001
go-go-mcp start --transport sse --port 3001

# In another terminal, connect using the client
./go-go-mcp client --transport sse --server http://localhost:3001 prompts list
go-go-mcp client --transport sse --server http://localhost:3001 prompts list
```

#### Using go-go-mcp as a Bridge

go-go-mcp can be used as a bridge to expose an SSE server as a stdio server. This is useful when you need to connect a stdio-based client to an SSE server:

```bash
# Start an SSE server on port 3000
go-go-mcp start --transport sse --port 3000

# In another terminal, start the bridge to expose the SSE server as stdio
go-go-mcp bridge --sse-url http://localhost:3000 --log-level debug

# Now you can use stdio-based clients to connect to the bridge
```

This is particularly useful when integrating with tools that only support stdio communication but need to connect to a web-based MCP server.

### Debug Mode

Add the `--debug` flag to enable detailed logging:

```bash
./go-go-mcp client --debug prompts list
go-go-mcp client --debug prompts list
```

### Version Information

Check the version:

```bash
./go-go-mcp version
go-go-mcp version
```

### Project Structure
## Configuration

- `pkg/`
- `protocol/` - Core protocol types and interfaces
- `prompts/` - Prompt registry and handlers
- `resources/` - Resource registry and handlers
- `tools/` - Tool registry and handlers
- `server/` - Server implementation
- `doc/` - Documentation
- `cmd/`
- `mcp-server/` - MCP server and client implementation
- `cmds/` - Command implementations
- `client/` - Client subcommands
go-go-mcp can be configured using YAML configuration files that allow you to:
- Define multiple profiles for different environments
- Configure tool and prompt sources
- Set parameter defaults and overrides
- Control access through blacklists/whitelists
- Manage security through parameter filtering

### Dependencies
For detailed configuration documentation, use:
```bash
# View configuration file documentation
go-go-mcp help config-file

# View example configuration
go-go-mcp help config-file --example
```

## Shell Commands

go-go-mcp supports defining custom shell commands in YAML files, providing:
- Template-based command generation with Go templates and Sprig functions
- Rich parameter type system
- Environment variable management
- Working directory control
- Error handling and output capture

- `github.com/rs/zerolog` - Structured logging
- `github.com/spf13/cobra` - Command-line interface
- Standard Go libraries
### Example Commands

The `examples/` directory contains various ready-to-use commands. You can view the schema for any command using `go-go-mcp schema <command.yaml>`, which shows the full parameter documentation that is passed to the LLM:

```bash
go-go-mcp schema examples/github/list-github-issues.yaml
```

## Contributing
#### GitHub Integration
- [`examples/github/list-github-issues.yaml`](examples/github/list-github-issues.yaml) - List and filter GitHub issues
- [`examples/github/list-pull-requests.yaml`](examples/github/list-pull-requests.yaml) - List and filter pull requests

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
#### Web Content Tools
- [`examples/shell-commands/fetch-url.yaml`](examples/shell-commands/fetch-url.yaml) - Fetch and process web content
- [`examples/html-extract/pubmed.yaml`](examples/html-extract/pubmed.yaml) - Search and extract data from PubMed

## License
#### Research and Documentation
- [`examples/shell-commands/diary-append.yaml`](examples/shell-commands/diary-append.yaml) - Maintain a timestamped diary
- [`examples/shell-commands/fetch-transcript.yaml`](examples/shell-commands/fetch-transcript.yaml) - Download YouTube video transcripts

[Insert your chosen license here]
For any command, you can view its full schema and documentation using:
```bash
# View the full parameter schema and documentation
go-go-mcp schema examples/github/list-github-issues.yaml

# View the command help
go-go-mcp run-command examples/github/list-github-issues.yaml --help
```

### Running Shell Commands Directly

You can run shell commands directly using the `run-command` subcommand. This allows you to execute any shell command YAML file without loading it into a server first:

```bash
# View command help and available flags
go-go-mcp run-command examples/github/list-github-issues.yaml --help

# Run a command with specific parameters
go-go-mcp run-command examples/github/list-github-issues.yaml --author wesen

# Run a Google Calendar command
go-go-mcp run-command examples/google/get-calendar.yaml --start today --end "next week"

# Run a URL fetching command
go-go-mcp run-command examples/shell-commands/fetch-url.yaml --url https://example.com
```

This provides a simpler way to use shell commands as standalone command-line tools without setting up a server.

### Generating Shell Commands with Pinocchio

You can use [Pinocchio](https://github.com/go-go-golems/pinocchio) to generate shell commands for go-go-mcp. First, add your local go-go-mcp repository as a Pinocchio repository:

```bash
pinocchio config repositories add $(pwd)/pinocchio
```

Then generate a new command using:

```bash
pinocchio go-go-mcp create-command --description "A command description"
```

This will create a new shell command YAML file with the appropriate structure and configuration.

For detailed shell commands documentation, use:
```bash
# View shell commands documentation
go-go-mcp help shell-commands

# View example shell commands
go-go-mcp help shell-commands --example
```

## Help System

go-go-mcp comes with comprehensive built-in documentation. To explore:

```bash
# List all available help topics
go-go-mcp help --all

# Get help on a specific topic
go-go-mcp help <topic>

# Show examples for a topic
go-go-mcp help <topic> --example
```

### Project Structure
Loading

0 comments on commit 898ec14

Please sign in to comment.