You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -4,109 +4,138 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
4
4
5
5
## Build Commands
6
6
7
-
### Build the server binary
8
7
```bash
9
-
make build
10
-
# Or directly:
11
-
go build -o bin/snmcp cmd/streamnative-mcp-server/main.go
12
-
```
13
-
14
-
### Run tests
15
-
```bash
16
-
go test -race ./...
17
-
# Run a specific test:
18
-
go test -race ./pkg/mcp/builders/...
19
-
```
20
-
21
-
### Docker operations
22
-
```bash
23
-
make docker-build # Build local Docker image
8
+
make build # Build server binary to bin/snmcp
9
+
go test -race ./... # Run all tests with race detection
10
+
go test -race ./pkg/mcp/builders/... # Run specific package tests
11
+
go test -v -run TestName ./pkg/... # Run a single test
12
+
make license-check # Check license headers
13
+
make license-fix # Fix license headers
14
+
make docker-build # Build local Docker image
24
15
make docker-build-push # Build and push multi-platform image
25
16
```
26
17
27
-
### License checking
28
-
```bash
29
-
make license-check # Check license headers
30
-
make license-fix # Fix license headers
31
-
```
32
-
33
18
## Architecture Overview
34
19
35
-
The StreamNative MCP Server implements the Model Context Protocol to enable AI agents to interact with Apache Kafka, Apache Pulsar, and StreamNative Cloud resources.
- Three types of sessions: SNCloudSession, KafkaSession, PulsarSession
41
-
- Sessions manage client connections and authentication
42
-
- Sessions are created and configured based on command-line flags
43
-
44
-
2.**MCP Server** (`pkg/mcp/`)
45
-
- Central server implementation using `mark3labs/mcp-go` library
46
-
- Handles tool registration and request routing
47
-
- Features can be enabled/disabled via `--features` flag
48
-
49
-
3.**Tool Builders** (`pkg/mcp/builders/`)
50
-
- Registry pattern for registering MCP tools
51
-
- Separate builders for Kafka and Pulsar operations
52
-
- Each builder creates tools with specific operations (admin, client, etc.)
20
+
The StreamNative MCP Server implements the Model Context Protocol using the `mark3labs/mcp-go` library to enable AI agents to interact with Apache Kafka, Apache Pulsar, and StreamNative Cloud resources.
53
21
54
-
4.**PFTools** (`pkg/mcp/pftools/`)
55
-
- Abstraction layer for Pulsar Functions as MCP tools
56
-
- Dynamic tool generation from deployed Pulsar Functions
57
-
- Circuit breaker pattern for resilience
58
-
- Schema handling for input/output validation
22
+
### Request Flow
59
23
60
-
### Key Design Patterns
61
-
62
-
1.**Builder Pattern**: Tool builders (`pkg/mcp/builders/`) register tools dynamically based on enabled features
63
-
2.**Session Pattern**: Separate sessions for different services (Kafka, Pulsar, SNCloud) with lazy initialization
64
-
3.**Registry Pattern**: Central registry (`pkg/mcp/builders/registry.go`) manages all tool builders
65
-
4.**Circuit Breaker**: Used in PFTools for handling function invocation failures
66
-
67
-
## Development Guidelines
68
-
69
-
### Adding New Tools
70
-
71
-
1. Create a new builder in `pkg/mcp/builders/kafka/` or `pkg/mcp/builders/pulsar/`
72
-
2. Implement the `Builder` interface with `Build()` method
73
-
3. Register the builder in the appropriate tools file (e.g., `kafka_admin_*_tools.go`)
74
-
4. Add feature flag support in `pkg/mcp/features.go`
75
-
76
-
### Session Context
77
-
78
-
The server maintains session context that gets passed to tools via the context:
79
-
- Pulsar admin client retrieval: Use `session.GetAdminClient()` or `session.GetAdminV3Client()`
80
-
- Kafka client retrieval: Use `session.GetKafkaSession()` methods
81
-
- Always check for nil sessions before use
82
-
83
-
### Error Handling
84
-
85
-
- Use wrapped errors with context: `fmt.Errorf("failed to X: %w", err)`
86
-
- Check session availability before operations
87
-
- Return meaningful error messages for AI agent consumption
24
+
```
25
+
Client Request → MCP Server (pkg/mcp/server.go)
26
+
↓
27
+
Tool Handler (from builders)
28
+
↓
29
+
Session Context (pkg/mcp/ctx.go)
30
+
↓
31
+
Service Client (Kafka/Pulsar/SNCloud)
32
+
```
88
33
89
-
##Testing
34
+
### Core Components
90
35
91
-
Tests follow standard Go testing patterns:
92
-
- Unit tests alongside source files (`*_test.go`)
93
-
- Use `testify`for assertions
94
-
- Mock external dependencies where appropriate
36
+
1.**Server & Sessions** (`pkg/mcp/server.go`)
37
+
-`Server` struct holds `MCPServer`, `KafkaSession`, `PulsarSession`, and `SNCloudSession`
38
+
- Sessions provide lazy-initialized clients for each service
39
+
- Context functions (`pkg/mcp/ctx.go`) inject/retrieve sessions from request context
0 commit comments