mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-21 09:28:14 +00:00
docs: 项目概览(OVERVIEW.md) + 插件开发指南(PLUGIN_DEV.md) + MCP 适配器插件
- OVERVIEW.md: 非技术用户友好的项目介绍和目标 - PLUGIN_DEV.md: 完整插件开发指南（含三种开发方式、API 参考、最佳实践） - internal/plugins/mcp/: MCP 协议适配器插件（JSON-RPC over stdio/SSE） - client.go: MCP 客户端（ListTools / CallTool） - stdio.go: 子进程 stdin/stdout 传输 - sse.go: HTTP POST 传输 - plugin.go: init() 自注册 + Settings 配置读取 - README.md 更新链接
This commit is contained in:
root
@ -2,6 +2,7 @@ package plugins
|
||||
|
||||
import (
|
||||
_ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/cli"
|
||||
_ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/mcp"
|
||||
_ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/openclaw"
|
||||
_ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/timer"
|
||||
_ "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/webui"
|
||||
|
||||
136
internal/plugins/mcp/client.go
Normal file
136
internal/plugins/mcp/client.go
Normal file
@ -0,0 +1,136 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"sync"
|
||||
)
|
||||
|
||||
// JSON-RPC 2.0 消息结构
|
||||
type rpcRequest struct {
|
||||
JSONRPC string `json:"jsonrpc"`
|
||||
ID int `json:"id"`
|
||||
Method string `json:"method"`
|
||||
Params interface{} `json:"params,omitempty"`
|
||||
}
|
||||
|
||||
type rpcResponse struct {
|
||||
JSONRPC string `json:"jsonrpc"`
|
||||
ID int `json:"id"`
|
||||
Result *json.RawMessage `json:"result,omitempty"`
|
||||
Error *rpcError `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
type rpcError struct {
|
||||
Code int `json:"code"`
|
||||
Message string `json:"message"`
|
||||
}
|
||||
|
||||
// MCP Tool 定义
|
||||
type MCPTool struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
InputSchema map[string]interface{} `json:"inputSchema"`
|
||||
}
|
||||
|
||||
// MCP 工具调用结果
|
||||
type MCPContent struct {
|
||||
Type string `json:"type"`
|
||||
Text string `json:"text,omitempty"`
|
||||
}
|
||||
|
||||
type MCPCallResult struct {
|
||||
Content []MCPContent `json:"content"`
|
||||
}
|
||||
|
||||
// Transport 抽象: 支持 stdio / SSE
|
||||
type Transport interface {
|
||||
Send(req *rpcRequest) (*rpcResponse, error)
|
||||
Close() error
|
||||
}
|
||||
|
||||
// Server 代表一个 MCP 服务器连接
|
||||
type Server struct {
|
||||
name string
|
||||
transport Transport
|
||||
mu sync.Mutex
|
||||
nextID int
|
||||
}
|
||||
|
||||
func NewServer(name string, t Transport) *Server {
|
||||
return &Server{name: name, transport: t}
|
||||
}
|
||||
|
||||
func (s *Server) Name() string { return s.name }
|
||||
|
||||
func (s *Server) nextRequestID() int {
|
||||
s.mu.Lock()
|
||||
defer s.mu.Unlock()
|
||||
s.nextID++
|
||||
return s.nextID
|
||||
}
|
||||
|
||||
// ListTools 列举 MCP 服务器提供的所有工具
|
||||
func (s *Server) ListTools() ([]MCPTool, error) {
|
||||
req := &rpcRequest{
|
||||
JSONRPC: "2.0",
|
||||
ID: s.nextRequestID(),
|
||||
Method: "tools/list",
|
||||
}
|
||||
resp, err := s.transport.Send(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("mcp %s tools/list: %w", s.name, err)
|
||||
}
|
||||
if resp.Error != nil {
|
||||
return nil, fmt.Errorf("mcp %s tools/list error: %s", s.name, resp.Error.Message)
|
||||
}
|
||||
if resp.Result == nil {
|
||||
return nil, nil
|
||||
}
|
||||
var result struct {
|
||||
Tools []MCPTool `json:"tools"`
|
||||
}
|
||||
if err := json.Unmarshal(*resp.Result, &result); err != nil {
|
||||
return nil, fmt.Errorf("mcp %s tools/list unmarshal: %w", s.name, err)
|
||||
}
|
||||
return result.Tools, nil
|
||||
}
|
||||
|
||||
// CallTool 调用 MCP 工具
|
||||
func (s *Server) CallTool(name string, args map[string]interface{}) (string, error) {
|
||||
req := &rpcRequest{
|
||||
JSONRPC: "2.0",
|
||||
ID: s.nextRequestID(),
|
||||
Method: "tools/call",
|
||||
Params: map[string]interface{}{
|
||||
"name": name,
|
||||
"arguments": args,
|
||||
},
|
||||
}
|
||||
resp, err := s.transport.Send(req)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s: %w", s.name, name, err)
|
||||
}
|
||||
if resp.Error != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s error: %s", s.name, name, resp.Error.Message)
|
||||
}
|
||||
if resp.Result == nil {
|
||||
return "", nil
|
||||
}
|
||||
var result MCPCallResult
|
||||
if err := json.Unmarshal(*resp.Result, &result); err != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s unmarshal: %w", s.name, name, err)
|
||||
}
|
||||
// 拼接所有文本片段
|
||||
var sb string
|
||||
for _, c := range result.Content {
|
||||
if c.Type == "text" {
|
||||
sb += c.Text
|
||||
}
|
||||
}
|
||||
return sb, nil
|
||||
}
|
||||
|
||||
func (s *Server) Close() error {
|
||||
return s.transport.Close()
|
||||
}
|
||||
147
internal/plugins/mcp/plugin.go
Normal file
147
internal/plugins/mcp/plugin.go
Normal file
@ -0,0 +1,147 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log"
|
||||
"sync"
|
||||
|
||||
"gitcode.com/JianFeeeee/HomeAgent/internal/plugin"
|
||||
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
)
|
||||
|
||||
// MCP 服务器配置（来自 config_mcp 表或 skill.json）
|
||||
type serverConfig struct {
|
||||
Name string `json:"name"`
|
||||
Command string `json:"command,omitempty"` // stdio 模式
|
||||
Args []string `json:"args,omitempty"`
|
||||
Env []string `json:"env,omitempty"`
|
||||
URL string `json:"url,omitempty"` // SSE 模式
|
||||
}
|
||||
|
||||
func init() {
|
||||
plugin.RegisterFactory("mcp", func(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return New(name), nil
|
||||
})
|
||||
}
|
||||
|
||||
type Plugin struct {
|
||||
name string
|
||||
servers []*Server
|
||||
mu sync.Mutex
|
||||
wg sync.WaitGroup
|
||||
}
|
||||
|
||||
func New(name string) *Plugin {
|
||||
return &Plugin{name: name}
|
||||
}
|
||||
|
||||
func (p *Plugin) Name() string { return p.name }
|
||||
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
// 从插件配置读取 MCP 服务器列表
|
||||
cfgs, err := p.loadConfig(s)
|
||||
if err != nil {
|
||||
return fmt.Errorf("load mcp config: %w", err)
|
||||
}
|
||||
if len(cfgs) == 0 {
|
||||
log.Printf("[mcp] no servers configured, idle")
|
||||
return nil
|
||||
}
|
||||
|
||||
for _, cfg := range cfgs {
|
||||
server, tools, err := p.connectServer(cfg)
|
||||
if err != nil {
|
||||
log.Printf("[mcp] connect %s: %v", cfg.Name, err)
|
||||
continue
|
||||
}
|
||||
|
||||
for _, tool := range tools {
|
||||
toolName := fmt.Sprintf("%s_%s", cfg.Name, tool.Name)
|
||||
tDef := sdk.ToolDef{
|
||||
Name: toolName,
|
||||
Description: fmt.Sprintf("[MCP/%s] %s", cfg.Name, tool.Description),
|
||||
Parameters: tool.InputSchema,
|
||||
}
|
||||
tHandler := p.makeHandler(server, tool.Name)
|
||||
if err := s.RegisterTool(toolName, tDef, tHandler); err != nil {
|
||||
log.Printf("[mcp] register tool %s: %v", toolName, err)
|
||||
continue
|
||||
}
|
||||
log.Printf("[mcp] registered tool: %s (%s)", toolName, cfg.Name)
|
||||
}
|
||||
|
||||
p.mu.Lock()
|
||||
p.servers = append(p.servers, server)
|
||||
p.mu.Unlock()
|
||||
log.Printf("[mcp] connected server: %s (%d tools)", cfg.Name, len(tools))
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) loadConfig(s *sdk.PluginSDK) ([]serverConfig, error) {
|
||||
// 优先从 skill.json（config map）读取
|
||||
raw, err := s.Settings().Get("servers")
|
||||
if err == nil {
|
||||
switch v := raw.(type) {
|
||||
case string:
|
||||
var cfgs []serverConfig
|
||||
if err := json.Unmarshal([]byte(v), &cfgs); err == nil && len(cfgs) > 0 {
|
||||
return cfgs, nil
|
||||
}
|
||||
case []interface{}:
|
||||
data, _ := json.Marshal(v)
|
||||
var cfgs []serverConfig
|
||||
if json.Unmarshal(data, &cfgs) == nil && len(cfgs) > 0 {
|
||||
return cfgs, nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 备用：从 JSON 文件读取
|
||||
// 没有配置时不报错，只返回空
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) connectServer(cfg serverConfig) (*Server, []MCPTool, error) {
|
||||
var transport Transport
|
||||
|
||||
if cfg.URL != "" {
|
||||
transport = NewSSETransport(cfg.URL)
|
||||
} else if cfg.Command != "" {
|
||||
var err error
|
||||
transport, err = NewStdioTransport(cfg.Command, cfg.Args, cfg.Env)
|
||||
if err != nil {
|
||||
return nil, nil, fmt.Errorf("stdio transport: %w", err)
|
||||
}
|
||||
} else {
|
||||
return nil, nil, fmt.Errorf("neither command nor url specified")
|
||||
}
|
||||
|
||||
server := NewServer(cfg.Name, transport)
|
||||
|
||||
tools, err := server.ListTools()
|
||||
if err != nil {
|
||||
transport.Close()
|
||||
return nil, nil, fmt.Errorf("list tools: %w", err)
|
||||
}
|
||||
|
||||
return server, tools, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) makeHandler(server *Server, toolName string) sdk.ToolHandler {
|
||||
return func(args map[string]interface{}) (interface{}, error) {
|
||||
return server.CallTool(toolName, args)
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) Stop() error {
|
||||
p.mu.Lock()
|
||||
defer p.mu.Unlock()
|
||||
for _, s := range p.servers {
|
||||
s.Close()
|
||||
}
|
||||
p.servers = nil
|
||||
return nil
|
||||
}
|
||||
61
internal/plugins/mcp/sse.go
Normal file
61
internal/plugins/mcp/sse.go
Normal file
@ -0,0 +1,61 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
// SSETransport 通过 HTTP POST 进行 JSON-RPC 通信（简化版，非流式）
|
||||
type SSETransport struct {
|
||||
url string
|
||||
client *http.Client
|
||||
pending map[int]chan *rpcResponse
|
||||
done chan struct{}
|
||||
}
|
||||
|
||||
func NewSSETransport(url string) *SSETransport {
|
||||
return &SSETransport{
|
||||
url: url,
|
||||
client: &http.Client{},
|
||||
pending: make(map[int]chan *rpcResponse),
|
||||
done: make(chan struct{}),
|
||||
}
|
||||
}
|
||||
func (t *SSETransport) Send(req *rpcRequest) (*rpcResponse, error) {
|
||||
data, err := json.Marshal(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("marshal: %w", err)
|
||||
}
|
||||
|
||||
httpReq, err := http.NewRequest("POST", t.url, bytes.NewReader(data))
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("http request: %w", err)
|
||||
}
|
||||
httpReq.Header.Set("Content-Type", "application/json")
|
||||
|
||||
resp, err := t.client.Do(httpReq)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("http post: %w", err)
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
|
||||
body, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read body: %w", err)
|
||||
}
|
||||
|
||||
var rpcResp rpcResponse
|
||||
if err := json.Unmarshal(body, &rpcResp); err != nil {
|
||||
return nil, fmt.Errorf("unmarshal response: %w", err)
|
||||
}
|
||||
|
||||
return &rpcResp, nil
|
||||
}
|
||||
|
||||
func (t *SSETransport) Close() error {
|
||||
close(t.done)
|
||||
return nil
|
||||
}
|
||||
122
internal/plugins/mcp/stdio.go
Normal file
122
internal/plugins/mcp/stdio.go
Normal file
@ -0,0 +1,122 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"os/exec"
|
||||
"sync"
|
||||
)
|
||||
|
||||
// StdioTransport 通过子进程 stdin/stdout 进行 JSON-RPC 通信
|
||||
type StdioTransport struct {
|
||||
cmd *exec.Cmd
|
||||
stdin io.WriteCloser
|
||||
stdout *bufio.Reader
|
||||
mu sync.Mutex
|
||||
pending map[int]chan *rpcResponse
|
||||
done chan struct{}
|
||||
}
|
||||
|
||||
func NewStdioTransport(command string, args []string, env []string) (*StdioTransport, error) {
|
||||
cmd := exec.Command(command, args...)
|
||||
if len(env) > 0 {
|
||||
cmd.Env = env
|
||||
}
|
||||
|
||||
stdin, err := cmd.StdinPipe()
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("stdin pipe: %w", err)
|
||||
}
|
||||
stdout, err := cmd.StdoutPipe()
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("stdout pipe: %w", err)
|
||||
}
|
||||
// 忽略 stderr（MCP 服务器可能输出日志到 stderr）
|
||||
cmd.Stderr = nil
|
||||
|
||||
if err := cmd.Start(); err != nil {
|
||||
return nil, fmt.Errorf("start %s: %w", command, err)
|
||||
}
|
||||
|
||||
t := &StdioTransport{
|
||||
cmd: cmd,
|
||||
stdin: stdin,
|
||||
stdout: bufio.NewReader(stdout),
|
||||
pending: make(map[int]chan *rpcResponse),
|
||||
done: make(chan struct{}),
|
||||
}
|
||||
|
||||
go t.readLoop()
|
||||
|
||||
return t, nil
|
||||
}
|
||||
|
||||
func (t *StdioTransport) readLoop() {
|
||||
dec := json.NewDecoder(t.stdout)
|
||||
for {
|
||||
var resp rpcResponse
|
||||
if err := dec.Decode(&resp); err != nil {
|
||||
close(t.done)
|
||||
// 通知所有等待的请求
|
||||
t.mu.Lock()
|
||||
for _, ch := range t.pending {
|
||||
close(ch)
|
||||
}
|
||||
t.pending = make(map[int]chan *rpcResponse)
|
||||
t.mu.Unlock()
|
||||
return
|
||||
}
|
||||
|
||||
t.mu.Lock()
|
||||
ch, ok := t.pending[resp.ID]
|
||||
delete(t.pending, resp.ID)
|
||||
t.mu.Unlock()
|
||||
|
||||
if ok {
|
||||
ch <- &resp
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (t *StdioTransport) Send(req *rpcRequest) (*rpcResponse, error) {
|
||||
data, err := json.Marshal(req)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("marshal request: %w", err)
|
||||
}
|
||||
|
||||
ch := make(chan *rpcResponse, 1)
|
||||
t.mu.Lock()
|
||||
t.pending[req.ID] = ch
|
||||
t.mu.Unlock()
|
||||
|
||||
if _, err := t.stdin.Write(data); err != nil {
|
||||
t.mu.Lock()
|
||||
delete(t.pending, req.ID)
|
||||
t.mu.Unlock()
|
||||
return nil, fmt.Errorf("write stdin: %w", err)
|
||||
}
|
||||
if _, err := t.stdin.Write([]byte("\n")); err != nil {
|
||||
t.mu.Lock()
|
||||
delete(t.pending, req.ID)
|
||||
t.mu.Unlock()
|
||||
return nil, fmt.Errorf("write newline: %w", err)
|
||||
}
|
||||
|
||||
select {
|
||||
case resp := <-ch:
|
||||
return resp, nil
|
||||
case <-t.done:
|
||||
return nil, fmt.Errorf("mcp transport closed")
|
||||
}
|
||||
}
|
||||
|
||||
func (t *StdioTransport) Close() error {
|
||||
t.stdin.Close()
|
||||
if t.cmd.Process != nil {
|
||||
t.cmd.Process.Kill()
|
||||
}
|
||||
<-t.done
|
||||
return t.cmd.Wait()
|
||||
}
|
||||
Reference in New Issue
Block a user