Content
# MCPsrv - MCP Server
[](https://goreportcard.com/report/github.com/asccclass/mcpsrv)
[](https://github.com/asccclass/mcpsrv/blob/main/LICENSE)
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
```bash
go get github.com/asccclass/mcpsrv
```
### Clone and Build
```bash
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
}
```
```go
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:
```go
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](https://github.com/emcie-co/parlant)
## Contact
Project maintainer: [asccclass](https://github.com/asccclass)
---
## 參考構思
```
// 設定 agent 參考資訊
agent.create_guideline(
condition=”Customer asks about refunds”,
action=”Check order status first to see if eligible”,
tools=[check_order_status],
)
```
