MCPsrv - MCP Server

MCPsrv is a lightweight MCP (Management Control Protocol) server implementation written in Go. It provides a flexible framework for handling MCP commands and managing connections.

Features

• Lightweight and efficient MCP server implementation
• Built-in support for common MCP commands
• Support for custom command handlers
• Simple configuration through environment variables
• Connection management with timeouts

Installation

目錄架構

.gitignore: Git 忽略檔案規則。
Dockerfile: 定義如何構建 Docker 映像檔。
README.md: 專案的說明文件。
auth.go: 與認證相關的功能。
clean.sh: 清理腳本。
envfile.example: 環境變數設定範例檔案。
go.mod: Go modules 設定。
go.sum: Go modules 的相依性摘要。
libs/: 自定義函式庫的目錄。
makefile: 編譯和自動化相關的指令。
router.go: 負責路由的功能。
server.go: 伺服器主程式。
tls.go: 與 TLS 加密協定相關的功能。
token.go: 與 Token 處理相關的功能。
tools/: 工具程式的目錄。
www/: 靜態網頁檔案的目錄。

Prerequisites

• Go 1.16 or higher

Using Go Get

go get github.com/asccclass/mcpsrv

Clone and Build

git clone https://github.com/asccclass/mcpsrv.git
cd mcpsrv
go build

Usage

Starting the Server

• 作為 MCP 服務端使用

import(
   "net/http"
   SherryServer "github.com/asccclass/sherryserver"
)

func NewRouter(srv *SherryServer.Server, documentRoot string, templateRoot string) *http.ServeMux {
   router := http.NewServeMux()
   // ...your router

   // Initial MCP Server
   mcpserver := SryMCPServer.NewMCPServer()
   mcpserver.AddRouter(router)
}

• tools 範例

package todoMCPServer

import(
   "fmt"
   "time"
   "net/http"
   "github.com/asccclass/mcpsrv/libs/mcpserver"
)

// TodoMCPServer MCP Server 結構
type TodoMCPServer struct {
   httpClient *http.Client
   API  string
}

// 註冊工具
func(app *TodoMCPServer) AddTools(s *SryMCPServer.MCPServer) {
   prompt := fmt.Sprintf(`你是一個待辦事項助手。請分析以下使用者輸入，判斷是否與待辦事項相關。

請依據使用者輸入，回應一個 JSON 格式，包含以下欄位：
- "is_related": true/false (是否與待辦事項相關)
- "action": "get_all_todos" | "get_todo_by_id" | "create_todo" | "update_todo" | "delete_todo" | "general_chat" (動作類型)
- "parameters": {} (相關參數，如果有的話)

請依據使用者輸入，回應一個 JSON 格式，包含以下欄位：
- "is_related": true/false (是否與待辦事項相關)
- "action": "get_all_todos" | "get_todo_by_id" | "create_todo" | "update_todo" | "delete_todo" | "general_chat" (動作類型)
- "parameters": {} (相關參數，如果有的話)

如果是與待辦事項相關：
- 查看/列出待辦事項 -> action: "get_all_todos"
- 查看特定待辦事項 -> action: "get_todo_by_id", parameters: {"id": "string"}
- 新增/建立待辦事項 -> action: "create_todo", parameters: {"context": "內容", "user": "負責者", "isFinished": "0"}
- 修改/更新待辦事項 -> action: "update_todo", parameters: {"id": "string", 其他要更新的欄位...}
- 刪除待辦事項 -> action: "delete_todo", parameters: {"id": "string"}
- 若欄位名稱為status/狀態時，請將欄位名稱替換為isFinish欄位：
   - 當status/狀態為「未處理」、「未分類」、「未知」或類似狀態時，isFinish應設為 "0"
   - 當status/狀態為「進行中」、「待處理」、「審核中」、「處理中/open/process/in progress」或類似狀態時，isFinish應設為 "1"
   - 當status/狀態為「完成/completed/done」、「已結束/closed」、「已處理/finished」或類似狀態時，isFinish應設為 "2"
   - 當status/狀態為「擱置/rejected」、「不處理」、「暫存/pause/suspended/pending」或類似狀態時，isFinish應設為 "3"
- 當使用者輸入的文字包含「時間相關語句」（如「明天上午十點」、「下週三下午三點」等），請根據「台北當前日期」進行解析，並將該時間轉換為 YYYY-MM-DD HH:MM:SS的時間格式。
   - 例如使用者輸入「明天上午十點開會」，判斷當前時間(如：2025-06-14）為基準，加一天後時間為 2025-06-15 10:00:00，並將此值存為欄位名稱：duetime。
   - 若時間資訊模糊（如「晚上」、「中午」），請估算合理時間（如「晚上」可設為 20:00:00）。
   - 若沒有指定年份、月份、日期，則年月日為當前西元年月日。
   - 輸出要求：
      - 時間應為完整的 UTC 格式時間字串（YYYY-MM-DD HH:MM:SS）。
      - 資料應儲存在欄位 duetime。

如果不是待辦事項相關 -> action: "general_chat"
請只回應 JSON，不要其他文字。
`)
   capz := &SryMCPServer.HostCapabilities {

      Version: "",
      ServerID: "0",
   }

   mcphost := &SryMCPServer.MCPHost {
      ID: "todo001",
      Name: "TODO",
      IsRelatedPrompt: prompt,
      ProcessPrompt: "",
   }
   // get_all_todos)註冊取得所有待辦事項的工具
   capz.Tools = append(capz.Tools, SryMCPServer.HostTool {
      Name: "get_all_todos",
      Description: "取得所有待辦事項",
      Parameters: make(map[string]string),
   })
   s.AddTool(SryMCPServer.Tool{
      Name:        "get_all_todos",
      Description: "取得所有待辦事項",
      InputSchema: SryMCPServer.InputSchema{
         Type:       "object",
         Properties: map[string]SryMCPServer.PropertySchema{},
      },
      Handler: app.getAllTodos,
   })
   // 註冊刪除待辦事項的工具
   capz.Tools = append(capz.Tools, SryMCPServer.HostTool {
      Name: "delete_todo",
      Description: "刪除待辦事項",
      Parameters: map[string]string{
         "id": "int",
      },
   })
   s.AddTool(SryMCPServer.Tool{
      Name:        "delete_todo",
      Description: "刪除待辦事項",
      InputSchema: SryMCPServer.InputSchema {
         Type: "object",
         Properties: map[string]SryMCPServer.PropertySchema{
            "id": {
               Type:        "int",
               Description: "要刪除的待辦事項ID",
            },
         },
         Required: []string{"id"},
      },
      Handler: app.deleteTodo,
   })
   mcphost.Capabilities = *capz
   s.Tools["todo"] = mcphost
}

// NewTodoMCPServer 建立新的 Todo MCP Server
func NewTodoMCPServer(todoapiurl string)(*TodoMCPServer, error) {
   if todoapiurl == "" {
      return nil, fmt.Errorf("todo api url endpoint is empty")
   }
   return &TodoMCPServer{
      httpClient: &http.Client{
         Timeout: 30 * time.Second,
      },
      API: todoapiurl,
   }, nil
}

package main

import (
    "github.com/asccclass/mcpsrv/server"
)

func main() {
    // Create a new server instance
    srv := server.NewServer()
    
    // Start the server
    srv.Start()
}

Environment Configuration

MCPsrv can be configured using environment variables:

• MCP_HOST: Host address to bind (default: "localhost")
• MCP_PORT: Port to listen on (default: "8080")
• MCP_TIMEOUT: Connection timeout in seconds (default: 60)

Adding Custom Command Handlers

You can extend MCPsrv with your own command handlers:

package main

import (
    "github.com/asccclass/mcpsrv/server"
    "github.com/asccclass/mcpsrv/handler"
)

func main() {
    srv := server.NewServer()
    
    // Register a custom command handler
    srv.RegisterHandler("CUSTOM_CMD", func(cmd *handler.Command) *handler.Response {
        return handler.NewResponse(200, "Custom command executed")
    })
    
    srv.Start()
}

API Documentation

Server

The server package provides the main server functionality:

• NewServer(): Creates a new MCP server instance
• Start(): Starts the server and listens for incoming connections
• RegisterHandler(cmd string, handler HandlerFunc): Registers a custom command handler

Handler

The handler package contains command handling utilities:

• Command: Represents an MCP command with parameters
• Response: Represents a response to an MCP command
• NewResponse(code int, message string): Creates a new response

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Reference

• Parlant

Contact

Project maintainer: asccclass

參考構思

// 設定 agent 參考資訊
agent.create_guideline(
   condition=”Customer asks about refunds”,
   action=”Check order status first to see if eligible”,
   tools=[check_order_status],
)