JinDaGe - mcps MCP Details

article

README

🚀 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 服务器，请按照以下步骤操作：

在项目根目录下创建一个新目录。
按照 MCP SDK 模式实现服务器。
更新 .github/workflows/image.yml 中的 GitHub Actions 工作流矩阵。
在本 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 - 开发版本。

🤝 贡献

分叉仓库。
创建一个功能分支。
进行更改。
如有必要，添加测试。
运行 make ci-local 确保所有检查通过。
提交拉取请求。

📄 许可证

本项目根据 LICENSE 文件中指定的条款进行许可。

📖 模型上下文协议

本项目实现了模型上下文协议（MCP）的服务器，该协议是将人工智能模型连接到外部数据源和工具的标准。有关 MCP 的更多信息，请访问官方文档。

mcps