Skip to content

Commit 555aafd

Browse files
doomsporkdoomspork
committed
docs: Add examples and declarative usage
1 parent 46b4d4d commit 555aafd

File tree

7 files changed

+563
-1
lines changed

7 files changed

+563
-1
lines changed

‎README.md‎

Lines changed: 129 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,14 +108,142 @@ uv pip install mcp-nixos
108108
```
109109

110110
### For Nix Users (You Know Who You Are)
111+
112+
#### Imperative Installation (Quick & Dirty)
111113
```bash
112114
# Run without installing
113115
nix run github:utensils/mcp-nixos
114116

115-
# Install to profile
117+
# Install to profile (not recommended for most Nix users)
116118
nix profile install github:utensils/mcp-nixos
117119
```
118120

121+
#### Declarative Installation (The Nix Way™)
122+
123+
Most Nix users prefer declarative configuration. Here's how to properly integrate MCP-NixOS:
124+
125+
##### Using Flakes (Recommended)
126+
127+
Add to your `flake.nix`:
128+
129+
```nix
130+
{
131+
inputs = {
132+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
133+
mcp-nixos.url = "github:utensils/mcp-nixos";
134+
};
135+
136+
outputs = { self, nixpkgs, mcp-nixos, ... }: {
137+
# For NixOS systems
138+
nixosConfigurations.mysystem = nixpkgs.lib.nixosSystem {
139+
modules = [
140+
({ pkgs, ... }: {
141+
environment.systemPackages = [
142+
mcp-nixos.packages.${pkgs.system}.default
143+
];
144+
})
145+
];
146+
};
147+
148+
# For Home Manager users
149+
homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
150+
modules = [
151+
({ pkgs, ... }: {
152+
home.packages = [
153+
mcp-nixos.packages.${pkgs.system}.default
154+
];
155+
})
156+
];
157+
};
158+
159+
# For nix-darwin (macOS) users
160+
darwinConfigurations.mymac = darwin.lib.darwinSystem {
161+
modules = [
162+
({ pkgs, ... }: {
163+
environment.systemPackages = [
164+
mcp-nixos.packages.${pkgs.system}.default
165+
];
166+
})
167+
];
168+
};
169+
};
170+
}
171+
```
172+
173+
##### Using Home Manager (without flakes)
174+
175+
Add to your `home.nix`:
176+
177+
```nix
178+
{ pkgs, ... }:
179+
180+
let
181+
mcp-nixos = pkgs.fetchFromGitHub {
182+
owner = "utensils";
183+
repo = "mcp-nixos";
184+
rev = "main"; # Or pin to a specific commit/tag
185+
sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
186+
};
187+
188+
mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
189+
in
190+
{
191+
home.packages = [
192+
mcp-nixos-pkg
193+
];
194+
}
195+
```
196+
197+
##### Using NixOS Configuration (without flakes)
198+
199+
Add to your `configuration.nix`:
200+
201+
```nix
202+
{ config, pkgs, ... }:
203+
204+
let
205+
mcp-nixos = pkgs.fetchFromGitHub {
206+
owner = "utensils";
207+
repo = "mcp-nixos";
208+
rev = "main"; # Or pin to a specific commit/tag
209+
sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
210+
};
211+
212+
mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
213+
in
214+
{
215+
environment.systemPackages = with pkgs; [
216+
mcp-nixos-pkg
217+
];
218+
}
219+
```
220+
221+
##### Using an Overlay
222+
223+
Create an overlay in `~/.config/nixpkgs/overlays/mcp-nixos.nix`:
224+
225+
```nix
226+
self: super: {
227+
mcp-nixos = super.callPackage (super.fetchFromGitHub {
228+
owner = "utensils";
229+
repo = "mcp-nixos";
230+
rev = "main";
231+
sha256 = "0000000000000000000000000000000000000000000000000000";
232+
} + "/default.nix") { };
233+
}
234+
```
235+
236+
Then use it in any Nix expression:
237+
```nix
238+
{ pkgs, ... }: {
239+
environment.systemPackages = [ pkgs.mcp-nixos ];
240+
}
241+
```
242+
243+
After installation, configure your MCP client as shown in the Quick Start section above.
244+
245+
📁 **See the `examples/` directory for complete, copy-paste ready configuration files for all installation methods.**
246+
119247
## Features Worth Mentioning
120248

121249
### 🚀 Version 1.0.1: The Async Revolution (After The Great Simplification)

‎default.nix‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{ pkgs ? import <nixpkgs> { } }:
2+
3+
let
4+
pythonVersion = "312";
5+
python = pkgs."python${pythonVersion}";
6+
ps = pkgs."python${pythonVersion}Packages";
7+
8+
pyproject = pkgs.lib.importTOML ./pyproject.toml;
9+
in
10+
ps.buildPythonApplication {
11+
pname = pyproject.project.name;
12+
inherit (pyproject.project) version;
13+
meta.mainProgram = pyproject.project.name;
14+
15+
src = ./.;
16+
17+
format = "pyproject";
18+
19+
nativeBuildInputs = with ps; [
20+
hatchling
21+
];
22+
23+
propagatedBuildInputs = with ps; [
24+
fastmcp
25+
requests
26+
beautifulsoup4
27+
];
28+
29+
# Disable runtime dependency checks since the available versions in nixpkgs
30+
# may not match exactly what's specified in pyproject.toml
31+
pythonImportsCheck = [ ];
32+
doCheck = false;
33+
dontCheckRuntimeDeps = true;
34+
}

‎examples/configuration.nix‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Example NixOS system configuration with MCP-NixOS
2+
# Add this to your /etc/nixos/configuration.nix or create a separate module
3+
4+
{ config, pkgs, lib, ... }:
5+
6+
let
7+
# For non-flake users: fetch MCP-NixOS from GitHub
8+
mcp-nixos-src = pkgs.fetchFromGitHub {
9+
owner = "utensils";
10+
repo = "mcp-nixos";
11+
rev = "main"; # Pin to a specific commit for reproducibility
12+
# To get the correct sha256:
13+
# nix-prefetch-github utensils mcp-nixos
14+
sha256 = lib.fakeSha256; # Replace with actual sha256
15+
};
16+
17+
# Build the package
18+
mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
19+
in
20+
{
21+
# Add MCP-NixOS to system-wide packages
22+
environment.systemPackages = with pkgs; [
23+
mcp-nixos
24+
# Other packages...
25+
];
26+
27+
# Optional: Configure MCP-NixOS for all users
28+
# This creates a system-wide configuration file
29+
environment.etc."claude/claude_desktop_config.json" = {
30+
text = builtins.toJSON {
31+
mcpServers = {
32+
nixos = {
33+
command = "${mcp-nixos}/bin/mcp-nixos";
34+
args = [];
35+
};
36+
};
37+
};
38+
# Make it readable by all users
39+
mode = "0644";
40+
};
41+
42+
# Optional: Create a systemd service to run MCP-NixOS as a system daemon
43+
# (Only useful if your MCP client supports network connections)
44+
systemd.services.mcp-nixos = {
45+
description = "MCP-NixOS Server";
46+
after = [ "network.target" ];
47+
wantedBy = [ "multi-user.target" ];
48+
49+
serviceConfig = {
50+
Type = "simple";
51+
ExecStart = "${mcp-nixos}/bin/mcp-nixos";
52+
Restart = "on-failure";
53+
RestartSec = 5;
54+
# Run as a non-privileged user
55+
User = "nobody";
56+
Group = "nogroup";
57+
# Security hardening
58+
PrivateTmp = true;
59+
ProtectSystem = "strict";
60+
ProtectHome = true;
61+
NoNewPrivileges = true;
62+
};
63+
64+
# Disable by default - users can enable if needed
65+
enable = false;
66+
};
67+
68+
# Optional: Create a shell alias for all users
69+
programs.bash.shellAliases = {
70+
mcp-nixos-test = "${mcp-nixos}/bin/mcp-nixos";
71+
};
72+
73+
# Optional: Add to the system path
74+
environment.variables = {
75+
MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
76+
};
77+
}

‎examples/darwin-configuration.nix‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Example nix-darwin configuration with MCP-NixOS for macOS
2+
# Add this to your darwin-configuration.nix or create a separate module
3+
4+
{ config, pkgs, lib, ... }:
5+
6+
let
7+
# For non-flake users: fetch MCP-NixOS from GitHub
8+
mcp-nixos-src = pkgs.fetchFromGitHub {
9+
owner = "utensils";
10+
repo = "mcp-nixos";
11+
rev = "main"; # Pin to a specific commit for reproducibility
12+
# To get the correct sha256:
13+
# nix-prefetch-github utensils mcp-nixos
14+
sha256 = lib.fakeSha256; # Replace with actual sha256
15+
};
16+
17+
# Build the package
18+
mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
19+
in
20+
{
21+
# Add MCP-NixOS to system-wide packages
22+
environment.systemPackages = with pkgs; [
23+
mcp-nixos
24+
# Other packages...
25+
];
26+
27+
# Configure Claude Desktop for all users
28+
# Note: Adjust path based on where Claude Desktop stores config on macOS
29+
environment.etc."claude/claude_desktop_config.json" = {
30+
text = builtins.toJSON {
31+
mcpServers = {
32+
nixos = {
33+
command = "${mcp-nixos}/bin/mcp-nixos";
34+
args = [];
35+
};
36+
};
37+
};
38+
};
39+
40+
# Create launchd service for MCP-NixOS (macOS equivalent of systemd)
41+
launchd.user.agents.mcp-nixos = {
42+
command = "${mcp-nixos}/bin/mcp-nixos";
43+
44+
serviceConfig = {
45+
Label = "org.nixos.mcp-nixos";
46+
RunAtLoad = false; # Don't start automatically
47+
KeepAlive = false; # Don't restart if it crashes
48+
StandardErrorPath = "/tmp/mcp-nixos.err";
49+
StandardOutPath = "/tmp/mcp-nixos.out";
50+
};
51+
};
52+
53+
# Add shell aliases for convenience
54+
programs.bash.interactiveShellInit = ''
55+
alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
56+
'';
57+
58+
programs.zsh.interactiveShellInit = ''
59+
alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
60+
'';
61+
62+
# Optional: Configure for Cursor on macOS
63+
# This assumes Cursor config is in the user's home directory
64+
system.activationScripts.postUserActivation.text = ''
65+
# Create Cursor MCP config for all users
66+
for user_home in /Users/*; do
67+
if [ -d "$user_home" ]; then
68+
cursor_config_dir="$user_home/.cursor"
69+
if [ ! -d "$cursor_config_dir" ]; then
70+
mkdir -p "$cursor_config_dir"
71+
fi
72+
73+
cat > "$cursor_config_dir/mcp.json" <<EOF
74+
{
75+
"mcpServers": {
76+
"nixos": {
77+
"command": "${mcp-nixos}/bin/mcp-nixos",
78+
"args": []
79+
}
80+
}
81+
}
82+
EOF
83+
fi
84+
done
85+
'';
86+
87+
# Set environment variable for easy reference
88+
environment.variables = {
89+
MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
90+
};
91+
}

0 commit comments

Comments
 (0)