MCP Servers Nix

🚀 MCP Server Configuration Guide

This guide provides a comprehensive overview of installing, configuring, and extending the MCP server using Nix. It covers installation methods, configuration examples, framework extensions, custom module options, testing, troubleshooting, and documentation resources.

📦 Installation

Installation with Flakes

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

Installation without Flakes

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

💻 Usage Examples

Basic Usage

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

Advanced Usage

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"
      ];
    };
  };
}

🔧 Technical Details

Adding New Server Packages

1. Official Packages: Place them in the pkgs/official/ directory.
2. Reference Implementations: Place them in the pkgs/reference/ directory.
3. Community Implementations: Place them in the pkgs/community/ directory.

Example: Adding a New Official Server Package

Create a new package definition file 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";
  };
}

Then register it in pkgs/default.nix:

{
  # ... existing packages ...
  
  new-mcp-server = pkgs.callPackage ./official/new-mcp-server { };
}

Module Configuration

Create a new module file modules/new-mcp-server.nix:

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

Defining Custom Options

Add the following to 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;
    };
  };
}

🧪 Testing and Verification

Testing with Flakes

nix flake test .

Testing without 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'

🐞 Troubleshooting

Common Issues

• Missing Dependencies: Check the dependencies in pkgs/default.nix.
• Configuration Errors: Ensure that the modules are correctly imported in configuration.nix or flake.nix.

📚 Documentation

Contribution Guide

Pull requests are welcome!

• Repository: GitHub

License

This project is licensed under the MIT License.