JinDaGe - mcp-servers-nix MCP Details

article

README

🚀 MCP 服务器配置指南

本指南旨在帮助您完成 MCP 服务器的安装、配置、扩展及相关问题的排查，助您顺利搭建和使用 MCP 服务器。

🚀 快速开始

📦 安装指南

本项目支持两种安装方式，您可以根据自身需求选择使用 flakes 或不使用 flakes 的方式进行安装。

使用 flakes 的安装方式

git clone https://github.com/yourusername/mcp-servers-nix.git
cd mcp-servers-nix
nix flake add . nixpkgs

不使用 flakes 的安装方式

git clone https://github.com/yourusername/mcp-servers-nix.git
cd mcp-servers-nix
nix-env -f . -i mcp-servers-nix

💻 使用示例

基础用法 - 默认配置

{
  mcp-servers.lib.mkConfig pkgs {
    programs = {
      filesystem = {
        enable = true;
        args = [ "/path/to/allowed/directory" ];
      };
    };
  };
}

高级用法 - 自定义配置

mcp-servers-nix.mcp-servers.lib.mkConfig pkgs {
  format = "yaml";
  fileName = "config.yaml";

  programs = {
    filesystem = {
      enable = true;
      args = [ "/path/to/allowed/directory" ];
    };
  };

  settings.servers = {
    custom-server = {
      command = "${pkgs.lib.getExe pkgs.nodejs "npx"}";
      args = [
        "-y"
        "custom-server-package"
        "/path/to/custom/server/path"
      ];
    };
  };
}

📚 详细文档

🔧 扩展框架

添加新服务器包

官方包：放置在 pkgs/official/ 目录下。
参考实现：放置在 pkgs/reference/ 目录下。
社区实现：放置在 pkgs/community/ 目录下。

示例：添加新官方服务器包

创建一个新的包定义文件 pkgs/official/new-mcp-server/default.nix：

{
  lib,
  fetchFromGitHub,
  buildNpmPackage,
}:

buildNpmPackage rec {
  pname = "new-mcp-server";
  version = "0.1.0";

  src = fetchFromGitHub {
    owner = "new-mcp-server";
    repo = "new-mcp-server";
    tag = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
  };

  npmDepsHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";

  meta = {
    description = "New MCP server";
    homepage = "https://github.com/new-mcp-server/new-mcp-server";
    license = lib.licenses.asl20;
    maintainers = with lib.maintainers; [ username ];
    mainProgram = "new-mcp-server";
  };
}

然后在 pkgs/default.nix 中注册：

{
  # ... 已经存在的包 ...
  
  new-mcp-server = pkgs.callPackage ./official/new-mcp-server { };
}

模块配置

创建一个新的模块文件 modules/new-mcp-server.nix：

{ mkServerModule, ... }:
{
  imports = [
    (mkServerModule {
      name = "new-mcp-server";
      packageName = "new-mcp-server";
    })
  ];
}

自定义模块选项

定义自定义选项

在 modules/new-mcp-server.nix 中添加：

{ config, pkgs, lib, mkServerModule, ... }:
let
  cfg = config.programs.new-mcp-server;
in
{
  imports = [
    (mkServerModule {
      name = "new-mcp-server";
      packageName = "new-mcp-server";
    })
  ];

  configuration = {
    options = {
      customOption ?= {
        type = "string";
        description = "A custom option for the new mcp server";
      };
    };

    content = {
      programs.new-mcp-server.enable = cfg.enable;
      programs.new-mcp-server.customOption = cfg.customOption;
    };
  };
}

测试与验证

使用 flakes 进行测试

nix flake test .

不使用 flakes 的测试方式

nix-shell --pure -E 'let { nixpkgs ?= import (fetchTarball "https://github.com/nix-community/interpreters/archive/master.tar.gz") {}; }' -I nixpkgs=. --run 'your-test-command'

问题排查

常见问题

依赖缺失：检查 pkgs/default.nix 中的依赖是否正确。
配置错误：确保在 configuration.nix 或 flake.nix 中正确导入模块。

文档与帮助

贡献指南

欢迎提交 Pull Request！

代码仓库：GitHub

📄 许可证

本项目遵循 MIT 协议。

mcp-servers-nix