Content
<h1 align="center">
<img alt="main logo" src="./docs/content/assets/logo.png" width="150"/>
<br/>
Foxy Contexts
</h1>
<!-- --8<-- [start:content] -->
<h4 align="center">Build MCP Servers Declaratively in Golang</h4>
<p align="center">
<a href="https://pkg.go.dev/github.com/strowk/foxy-contexts"><img src="https://pkg.go.dev/badge/github.com/strowk/foxy-contexts.svg" alt="Go Reference"></a>
<a href="https://goreportcard.com/report/github.com/strowk/foxy-contexts"><img src="https://goreportcard.com/badge/github.com/strowk/foxy-contexts" alt="Go Reference"></a>
<a href="https://github.com/strowk/foxy-contexts/actions/workflows/test.yaml"><img src="https://github.com/strowk/foxy-contexts/actions/workflows/test.yaml/badge.svg"/></a>
<a href="https://github.com/strowk/foxy-contexts/actions/workflows/golangci-lint.yaml"><img src="https://github.com/strowk/foxy-contexts/actions/workflows/golangci-lint.yaml/badge.svg"/></a>
</p>
<p align="center">
<a href="#features">Features</a> 🦊
<a href="#tool-example">Tool Example</a> 🦊
<a href="https://foxy-contexts.str4.io">Docs</a> 🦊
<a href="https://github.com/strowk/foxy-contexts">Sources</a>
</p>
Foxy contexts is a Golang library for building context servers supporting [Model Context Protocol](https://modelcontextprotocol.io/).
This library only supports server side of the protocol. Using it you can build context servers using declarative approach, by defining [tools](https://modelcontextprotocol.io/docs/concepts/tools), [resources](https://modelcontextprotocol.io/docs/concepts/resources) and [prompts](https://modelcontextprotocol.io/docs/concepts/prompts) and then registering them with your app.Builder, which is using [uber's fx](https://github.com/uber-go/fx) App under the hood and you can inject into its container as well.
With this approach you can easily colocate call/read/get logic and definitions of your tools/resources/prompts in a way that every tool/resource/prompt is placed in a separate place, while Dependency Injection allows you to reuse shared parts like clients, database connections, etc.
## Features
Here is list of features that are implemented and planned:
- [x] Base (lifecycle/ping)
- [ ] Progress (planned)
- [x] Transports
- [x] Stdio Transport
- [x] SSE Transport
- [x] Streamable HTTP Transport (beta)
- [x] Tools
- [x] Package toolinput helps define tools input schema and validate arriving input
- [ ] Resources
- [x] Resources - static
- [x] Resources - dynamic via Resource Providers
- [ ] Resources - dynamic via Resource Templates (planned)
- [ ] Resource Templates completion (planned)
- [ ] Resource subscriptions
- [x] Prompts
- [x] Prompts Completion
- [x] Functional Testing package foxytest
- [x] Simple building of your MCP server with the power of Dependency Injection
- [ ] Logging via MCP (planned)
- [ ] Sampling (planned)
- [ ] Roots (planned)
- [ ] Pagination (planned)
- [ ] Notifications list_changed (planned)
- [x] Testing - functional tests with foxytest package
Check [docs](https://foxy-contexts.str4.io/) and [examples](https://github.com/strowk/foxy-contexts/tree/main/examples) to know more.
## Tool Example
For example try following
```bash
git clone https://github.com/strowk/foxy-contexts
cd foxy-contexts/examples/list_current_dir_files_tool
npx @modelcontextprotocol/inspector go run main.go
```
, then once inspector is started in browser open http://localhost:6274 and try to use list-current-dir-files.
Here's the code of that example from [examples/list_current_dir_files_tool/main.go](https://github.com/strowk/foxy-contexts/blob/main/examples/list_current_dir_files_tool/main.go) (in real world application you would probably want to split it into multiple files):
```go
package main
import (
"fmt"
"os"
"github.com/strowk/foxy-contexts/pkg/app"
"github.com/strowk/foxy-contexts/pkg/fxctx"
"github.com/strowk/foxy-contexts/pkg/mcp"
"github.com/strowk/foxy-contexts/pkg/stdio"
"go.uber.org/fx"
"go.uber.org/fx/fxevent"
"go.uber.org/zap"
)
// This example defines list-current-dir-files tool for MCP server, that prints files in the current directory
// , run it with:
// npx @modelcontextprotocol/inspector go run main.go
// , then in browser open http://localhost:6274
// , then click Connect
// , then click List Tools
// , then click list-current-dir-files
// NewListCurrentDirFilesTool defines a tool that lists files in the current directory
func NewListCurrentDirFilesTool() fxctx.Tool {
return fxctx.NewTool(
// This information about the tool would be used when it is listed:
&mcp.Tool{
Name: "list-current-dir-files",
Description: Ptr("Lists files in the current directory"),
InputSchema: mcp.ToolInputSchema{
Type: "object",
Properties: map[string]map[string]interface{}{},
Required: []string{},
},
},
// This is the callback that would be executed when the tool is called:
func(_ context.Context, args map[string]interface{}) *mcp.CallToolResult {
files, err := os.ReadDir(".")
if err != nil {
return &mcp.CallToolResult{
IsError: Ptr(true),
Meta: map[string]interface{}{},
Content: []interface{}{
mcp.TextContent{
Type: "text",
Text: fmt.Sprintf("failed to read dir: %v", err),
},
},
}
}
var contents []interface{} = make([]interface{}, len(files))
for i, f := range files {
contents[i] = mcp.TextContent{
Type: "text",
Text: f.Name(),
}
}
return &mcp.CallToolResult{
Meta: map[string]interface{}{},
Content: contents,
IsError: Ptr(false),
}
},
)
}
func main() {
app.
NewBuilder().
// adding the tool to the app
WithTool(NewListCurrentDirFilesTool).
// setting up server
WithName("list-current-dir-files").
WithVersion("0.0.1").
WithTransport(stdio.NewTransport()).
// Configuring fx logging to only show errors
WithFxOptions(fx.Provide(func() *zap.Logger {
cfg := zap.NewDevelopmentConfig()
cfg.Level.SetLevel(zap.ErrorLevel)
logger, _ := cfg.Build()
return logger
}),
fx.Option(fx.WithLogger(
func(logger *zap.Logger) fxevent.Logger {
return &fxevent.ZapLogger{Logger: logger}
},
)),
).
Run()
}
func Ptr[T any](v T) *T {
return &v
}
```
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors