Skip to content

Commit d56e966

Browse files
localai-botlocalai-bot
authored
feat: add sub-agent MCP server with OpenAI chat completion support (#19)
* feat: add sub-agent MCP server with OpenAI chat completion support - Add new sub-agent directory with main.go and README.md - Implement sub_agent_send tool for chat completions - Implement sub_agent_list tool to list active jobs - Implement sub_agent_get_result tool to retrieve results - Support background job tracking with goroutines - In-memory storage with configurable TTL - Add go-openai dependency for OpenAI API calls * Remove binary file from repository * docs: add sub-agent server documentation to top-level README --------- Co-authored-by: localai-bot <localai-bot@users.noreply.github.com>
1 parent e1e1142 commit d56e966

5 files changed

Lines changed: 467 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1581,3 +1581,59 @@ This project is licensed under the terms specified in the [LICENSE](LICENSE) fil
15811581
This project implements servers for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), a standard for connecting AI models to external data sources and tools.
15821582

15831583
For more information about MCP, visit the [official documentation](https://modelcontextprotocol.io/docs).
1584+
1585+
### 🤖 Sub-Agent Server
1586+
1587+
A Model Context Protocol (MCP) server that allows sending chat completion messages to any OpenAI-compatible endpoint, with support for background job tracking using goroutines and in-memory storage with TTL.
1588+
1589+
**Features:**
1590+
- Send chat completion requests to OpenAI-compatible endpoints
1591+
- Background job tracking with asynchronous execution
1592+
- In-memory storage with configurable TTL for results
1593+
- Three MCP tools for managing sub-agent calls
1594+
1595+
**Tools:**
1596+
- `sub_agent_send` - Send a chat completion message to an OpenAI-compatible endpoint
1597+
- `sub_agent_list` - List all active sub-agent calls with their status
1598+
- `sub_agent_get_result` - Get the result of a completed sub-agent call by task ID
1599+
1600+
**Configuration:**
1601+
- `OPENAI_BASE_URL` - The base URL for the OpenAI API endpoint (default: `https://api.openai.com/v1`)
1602+
- `OPENAI_MODEL` - The model to use for chat completions (default: `gpt-3.5-turbo`)
1603+
- `OPENAI_API_KEY` - The API key for authentication (required)
1604+
- `TTL` - Time-to-live for stored results in Go duration format (default: `1h`)
1605+
1606+
**Docker Image:**
1607+
```bash
1608+
docker run -e OPENAI_API_KEY=your-key ghcr.io/mudler/mcps/sub-agent:latest
1609+
```
1610+
1611+
**LocalAI configuration (to add to the model config):**
1612+
```yaml
1613+
mcp:
1614+
stdio: |
1615+
{
1616+
"mcpServers": {
1617+
"sub-agent": {
1618+
"command": "docker",
1619+
"env": {
1620+
"OPENAI_BASE_URL": "https://your-openai-compatible-endpoint/v1",
1621+
"OPENAI_MODEL": "your-model",
1622+
"OPENAI_API_KEY": "your-api-key",
1623+
"TTL": "2h"
1624+
},
1625+
"args": [
1626+
"run", "-i", "--rm",
1627+
"-e", "OPENAI_BASE_URL",
1628+
"-e", "OPENAI_MODEL",
1629+
"-e", "OPENAI_API_KEY",
1630+
"-e", "TTL",
1631+
"ghcr.io/mudler/mcps/sub-agent:master"
1632+
]
1633+
}
1634+
}
1635+
}
1636+
```
1637+
1638+
For more details, see the [sub-agent README](./sub-agent/README.md).
1639+

‎go.mod‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ require (
1313
github.com/mudler/go-processmanager v0.1.0
1414
github.com/onsi/ginkgo/v2 v2.28.1
1515
github.com/onsi/gomega v1.39.1
16+
github.com/sashabaranov/go-openai v1.41.2
1617
github.com/tmc/langchaingo v0.1.13
1718
golang.org/x/crypto v0.47.0
1819
)

‎go.sum‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
147147
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
148148
github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
149149
github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
150+
github.com/sashabaranov/go-openai v1.41.2 h1:vfPRBZNMpnqu8ELsclWcAvF19lDNgh1t6TVfFFOPiSM=
151+
github.com/sashabaranov/go-openai v1.41.2/go.mod h1:lj5b/K+zjTSFxVLijLSTDZuP7adOgerWeFyZLUhAKRg=
150152
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
151153
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
152154
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=

‎sub-agent/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# sub-agent MCP Server
2+
3+
A Model Context Protocol (MCP) server that allows sending chat completion messages to any OpenAI-compatible endpoint, with support for background job tracking using goroutines and in-memory storage with TTL.
4+
5+
## Features
6+
7+
- Send chat completion requests to OpenAI-compatible endpoints
8+
- Background job tracking with asynchronous execution
9+
- In-memory storage with configurable TTL for results
10+
- Three MCP tools for managing sub-agent calls
11+
12+
## Configuration
13+
14+
The server is configured via environment variables:
15+
16+
| Variable | Description | Default |
17+
|----------|-------------|---------|
18+
| `OPENAI_BASE_URL` | The base URL for the OpenAI API endpoint | `https://api.openai.com/v1` |
19+
| `OPENAI_MODEL` | The model to use for chat completions | `gpt-3.5-turbo` |
20+
| `OPENAI_API_KEY` | The API key for authentication | Required |
21+
| `TTL` | Time-to-live for stored results (Go duration format) | `1h` |
22+
23+
## MCP Tools
24+
25+
### `sub_agent_send`
26+
27+
Send a chat completion message to an OpenAI-compatible endpoint.
28+
29+
**Input:**
30+
- `message` (string, required): The message to send to the OpenAI endpoint
31+
- `background` (boolean, optional): Whether to run the request in the background (default: false)
32+
- `model` (string, optional): Override the default model for this request
33+
34+
**Output:**
35+
- If synchronous: Returns the completion result directly
36+
- If background: Returns a task ID for tracking
37+
38+
### `sub_agent_list`
39+
40+
List all active sub-agent calls with their status and creation time.
41+
42+
**Input:** None
43+
44+
**Output:**
45+
- `results`: Array of sub-agent result objects
46+
- `count`: Number of active results
47+
48+
### `sub_agent_get_result`
49+
50+
Get the result of a completed sub-agent call by task ID.
51+
52+
**Input:**
53+
- `task_id` (string, required): The task ID to retrieve the result for
54+
55+
**Output:**
56+
- `result`: The sub-agent result object, or error if not found/expired
57+
58+
## Usage
59+
60+
### Building
61+
62+
```bash
63+
cd sub-agent
64+
go build -o sub-agent main.go
65+
```
66+
67+
### Running
68+
69+
```bash
70+
export OPENAI_BASE_URL="https://your-openai-compatible-endpoint/v1"
71+
export OPENAI_MODEL="your-model"
72+
export OPENAI_API_KEY="your-api-key"
73+
export TTL="2h"
74+
75+
./sub-agent
76+
```
77+
78+
### Example: Synchronous Request
79+
80+
```json
81+
{
82+
"tool": "sub_agent_send",
83+
"arguments": {
84+
"message": "Hello, how are you?"
85+
}
86+
}
87+
```
88+
89+
### Example: Background Request
90+
91+
```json
92+
{
93+
"tool": "sub_agent_send",
94+
"arguments": {
95+
"message": "Generate a summary of the following text...",
96+
"background": true
97+
}
98+
}
99+
// Returns: {"task_id": "uuid", "status": "queued"}
100+
```
101+
102+
### Example: List All Jobs
103+
104+
```json
105+
{
106+
"tool": "sub_agent_list",
107+
"arguments": {}
108+
}
109+
```
110+
111+
### Example: Get Result
112+
113+
```json
114+
{
115+
"tool": "sub_agent_get_result",
116+
"arguments": {
117+
"task_id": "uuid-from-background-request"
118+
}
119+
}
120+
```
121+
122+
## Architecture
123+
124+
- **In-memory Store**: Uses a thread-safe map with read/write locks for concurrent access
125+
- **TTL Cleanup**: Background goroutine periodically removes expired entries (runs every minute)
126+
- **OpenAI Client**: Uses the `github.com/sashabaranov/go-openai` library for API calls
127+
- **UUID Generation**: Uses `github.com/google/uuid` for unique task IDs
128+
129+
## Dependencies
130+
131+
- `github.com/modelcontextprotocol/go-sdk`: MCP protocol implementation
132+
- `github.com/sashabaranov/go-openai`: OpenAI API client
133+
- `github.com/google/uuid`: UUID generation

0 commit comments

Comments
 (0)