Mcps

🚀 MCPS - 模型上下文協議服務器

本倉庫包含模型上下文協議（MCP）服務器，為人工智能模型提供了各種工具和功能。該項目最初是為 LocalAI 提供小示例而開發的，但也適用於任何 MCP 客戶端。

🚀 快速開始

本項目提供了多種類型的 MCP 服務器，你可以根據需求選擇合適的服務器進行部署和使用。以下是一些快速開始的步驟和示例。

可用服務器

🦆 DuckDuckGo 搜索服務器

這是一個使用 DuckDuckGo 提供搜索功能的網絡搜索服務器。

• 特性：
  • 具備網絡搜索功能。
  • 可配置最大搜索結果數量（默認值為 5）。
  • 對輸入/輸出進行 JSON 模式驗證。
• 工具：
  • search - 在網絡上搜索信息。
• 配置：
  • MAX_RESULTS - 用於設置最大搜索結果數量的環境變量（默認值為 5）。
• Docker 鏡像：

docker run -e MAX_RESULTS=10 ghcr.io/mudler/mcps/duckduckgo:latest

• LocalAI 配置（添加到模型配置中）：

mcp:
  stdio: |
    {
      "mcpServers": {
        "ddg": {
          "command": "docker",
          "env": {
            "MAX_RESULTS": "10"
          },
          "args": [
            "run", "-i", "--rm", "-e", "MAX_RESULTS",
            "ghcr.io/mudler/mcps/duckduckgo:master"
          ]
        }
      }
    }

🌤️ 天氣服務器

這是一個提供全球城市當前天氣和天氣預報數據的天氣信息服務器。

• 特性：
  • 提供當前天氣狀況（溫度、風速、天氣描述）。
  • 提供多日天氣預報。
  • 對包含特殊字符的城市名稱進行 URL 編碼。
  • 對輸入/輸出進行 JSON 模式驗證。
  • 處理 HTTP 超時。
• 工具：
  • get_weather - 獲取某個城市的當前天氣和天氣預報。
• API 響應格式：

{
  "temperature": "29 °C",
  "wind": "20 km/h", 
  "description": "Partly cloudy",
  "forecast": [
    {
      "day": "1",
      "temperature": "27 °C",
      "wind": "12 km/h"
    },
    {
      "day": "2", 
      "temperature": "22 °C",
      "wind": "8 km/h"
    }
  ]
}

• Docker 鏡像：

docker run ghcr.io/mudler/mcps/weather:latest

• LocalAI 配置（添加到模型配置中）：

mcp:
  stdio: |
    {
      "mcpServers": {
        "weather": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "ghcr.io/mudler/mcps/weather:master"
          ]
        }
      }
    }

🧠 內存服務器

這是一個持久化內存存儲服務器，允許人工智能模型在不同會話中存儲、檢索和管理信息。

• 特性：
  • 採用持久化 JSON 文件存儲。
  • 可以添加、列出和刪除內存條目。
  • 為每個條目生成唯一 ID。
  • 跟蹤條目的時間戳。
  • 可配置存儲位置。
  • 對輸入/輸出進行 JSON 模式驗證。
• 工具：
  • add_memory - 向內存存儲中添加新條目。
  • list_memory - 列出所有內存條目。
  • remove_memory - 按 ID 刪除內存條目。
  • search_memory - 按內容搜索內存條目（不區分大小寫）。
• 配置：
  • MEMORY_FILE_PATH - 用於設置內存文件路徑的環境變量（默認值為 /data/memory.json）。
• 內存條目格式：

{
  "id": "1703123456789000000",
  "content": "User prefers coffee over tea",
  "created_at": "2023-12-21T10:30:56.789Z"
}

• 搜索響應格式：

{
  "query": "coffee",
  "results": [
    {
      "id": "1703123456789000000",
      "content": "User prefers coffee over tea",
      "created_at": "2023-12-21T10:30:56.789Z"
    }
  ],
  "count": 1
}

• Docker 鏡像：

docker run -e MEMORY_FILE_PATH=/custom/path/memory.json ghcr.io/mudler/mcps/memory:latest

• LocalAI 配置（添加到模型配置中）：

mcp:
  stdio: |
    {
      "mcpServers": {
        "memory": {
          "command": "docker",
          "env": {
            "MEMORY_FILE_PATH": "/data/memory.json"
          },
          "args": [
            "run", "-i", "--rm", "-v", "/host/data:/data",
            "ghcr.io/mudler/mcps/memory:master"
          ]
        }
      }
    }

🔧 開發

前提條件

• Go 1.24.7 或更高版本。
• Docker（用於容器化構建）。
• Make（用於使用 Makefile）。

構建

使用提供的 Makefile 進行輕鬆開發：

# 顯示所有可用命令
make help

# 開發工作流程
make dev

# 構建特定服務器
make MCP_SERVER=duckduckgo build
make MCP_SERVER=weather build
make MCP_SERVER=memory build

# 運行測試和檢查
make ci-local

# 構建多架構鏡像
make build-multiarch

添加新服務器

要添加新的 MCP 服務器，請按照以下步驟操作：

1. 在項目根目錄下創建一個新目錄。
2. 按照 MCP SDK 模式實現服務器。
3. 更新 .github/workflows/image.yml 中的 GitHub Actions 工作流矩陣。
4. 在本 README 中更新新服務器的信息。

示例服務器結構：

package main

import (
    "context"
    "log"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
    server := mcp.NewServer(&mcp.Implementation{
        Name: "your-server", 
        Version: "v1.0.0"
    }, nil)
    
    // 在這裡添加你的工具
    mcp.AddTool(server, &mcp.Tool{
        Name: "your-tool", 
        Description: "your tool description"
    }, YourToolFunction)
    
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

🐳 Docker 鏡像

Docker 鏡像會自動構建並推送到 GitHub 容器註冊表：

• ghcr.io/mudler/mcps/duckduckgo:latest - 最新的 DuckDuckGo 服務器。
• ghcr.io/mudler/mcps/duckduckgo:v1.0.0 - 帶標籤的版本。
• ghcr.io/mudler/mcps/duckduckgo:master - 開發版本。
• ghcr.io/mudler/mcps/weather:latest - 最新的天氣服務器。
• ghcr.io/mudler/mcps/weather:v1.0.0 - 帶標籤的版本。
• ghcr.io/mudler/mcps/weather:master - 開發版本。
• ghcr.io/mudler/mcps/memory:latest - 最新的內存服務器。
• ghcr.io/mudler/mcps/memory:v1.0.0 - 帶標籤的版本。
• ghcr.io/mudler/mcps/memory:master - 開發版本。

🤝 貢獻

1. 分叉倉庫。
2. 創建一個功能分支。
3. 進行更改。
4. 如有必要，添加測試。
5. 運行 make ci-local 確保所有檢查通過。
6. 提交拉取請求。

📄 許可證

本項目根據 LICENSE 文件中指定的條款進行許可。

📖 模型上下文協議

本項目實現了 模型上下文協議（MCP） 的服務器，該協議是將人工智能模型連接到外部數據源和工具的標準。 有關 MCP 的更多信息，請訪問 官方文檔。