Skip to content

Commit

Permalink
✨ Add more documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@wesen
wesen committed Feb 11, 2025
1 parent 23ff5cd commit 73ea104
Show file tree
Hide file tree
Showing 6 changed files with 1,071 additions and 276 deletions.
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
31 changes: 30 additions & 1 deletion changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -859,4 +859,33 @@ Added notification handling support to the stdio transport:
- Added notification handler to StdioTransport struct
- Implemented SetNotificationHandler method
- Added notification detection and handling in Send method
- Improved response handling to properly handle interleaved notifications
- Improved response handling to properly handle interleaved notifications

## Documentation: Added Pinocchio Integration Instructions

Added documentation about using Pinocchio to generate shell commands for go-go-mcp.

- Added section about adding go-go-mcp as a Pinocchio repository
- Added instructions for using the create-command template

## Documentation: Added Run Command Usage Instructions

Added documentation about using the run-command subcommand to execute shell commands directly as standalone command-line tools.

- Added section about using run-command with shell command YAML files
- Added examples for different types of commands (GitHub, Google Calendar, URL fetching)

## Documentation: Added Example Commands Overview

Added a comprehensive overview of example commands available in the examples directory.

- Added categorized listing of example commands (GitHub, Google Calendar, Web Content, etc.)
- Added brief descriptions for each command
- Improved discoverability of available tools

## Documentation: Added Schema Command and Improved Example Links

Enhanced the example commands documentation:
- Added information about using the schema command to view parameter documentation
- Converted example command paths to clickable markdown links
- Added examples of viewing command documentation using both schema and help
Loading

0 comments on commit 73ea104

Please sign in to comment.