AGENTS.md
This commit is contained in:
MCP Packages
208
AGENTS.md
Normal file
208
AGENTS.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# AGENTS.md - MCP Server Packages for Nix
|
||||
|
||||
This repository provides Nix derivations for MCP (Model Context Protocol) servers
|
||||
not yet available in nixpkgs.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Description |
|
||||
|----------------------------------|------------------------------------|
|
||||
| `nix build .#<package-name>` | Build a specific package |
|
||||
| `nix build .#default` | Build all packages |
|
||||
| `nix flake show` | List available packages |
|
||||
| `nix flake check` | Validate flake syntax and outputs |
|
||||
| `nix develop` | Enter development shell |
|
||||
|
||||
## Build Commands
|
||||
|
||||
```bash
|
||||
nix build .#manim-mcp-server # Build specific package
|
||||
nix build .#default # Build all packages
|
||||
./result/bin/<package-name> # Test built package
|
||||
nix flake check # Validate flake
|
||||
nix flake update # Update dependencies
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
This repository has no unit tests. Validation is done via successful `nix build`.
|
||||
To verify a package works:
|
||||
|
||||
1. Build it: `nix build .#<package-name>`
|
||||
2. Run it: `./result/bin/<package-name>`
|
||||
3. Check the flake: `nix flake check`
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
packages/
|
||||
├── default.nix # Package aggregator - registers all packages
|
||||
└── <package-name>/
|
||||
└── package.nix # Package derivation
|
||||
|
||||
overlays/
|
||||
└── default.nix # Nix overlay that exports all MCP packages
|
||||
|
||||
flake.nix # Main flake definition
|
||||
flake.lock # Locked dependency versions
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Nix Formatting
|
||||
|
||||
- Use 2-space indentation
|
||||
- Place opening braces on the same line
|
||||
- Use `rec` only when self-references are needed
|
||||
- Prefer `let...in` blocks for local bindings
|
||||
- Use attribute sets with one attribute per line for readability
|
||||
|
||||
### Function Arguments
|
||||
|
||||
Format function arguments with each parameter on its own line:
|
||||
```nix
|
||||
{
|
||||
lib,
|
||||
stdenv,
|
||||
fetchFromGitHub,
|
||||
makeWrapper,
|
||||
python3,
|
||||
}:
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Package names**: lowercase with hyphens (e.g., `manim-mcp-server`)
|
||||
- **Variables**: camelCase for local variables (e.g., `mcpPackages`, `allMcpServers`)
|
||||
- **Attribute names**: lowercase with hyphens in package sets
|
||||
- **Version strings**: Use `x.x.x-unstable` for development versions pinned to commits
|
||||
|
||||
### Package Structure
|
||||
|
||||
Each package lives in `packages/<package-name>/package.nix`. Register new packages
|
||||
in `packages/default.nix`:
|
||||
|
||||
```nix
|
||||
{ pkgs }:
|
||||
{
|
||||
manim-mcp-server = pkgs.callPackage ./manim-mcp-server/package.nix { };
|
||||
new-package = pkgs.callPackage ./new-package/package.nix { };
|
||||
}
|
||||
```
|
||||
|
||||
### Hash Calculation
|
||||
|
||||
When adding new packages, use `lib.fakeHash` initially:
|
||||
```nix
|
||||
hash = lib.fakeHash;
|
||||
```
|
||||
|
||||
Then run `nix build` and copy the correct hash from the error message.
|
||||
|
||||
### Meta Attributes
|
||||
|
||||
Always include these meta attributes:
|
||||
```nix
|
||||
meta = with lib; {
|
||||
description = "Short description of the MCP server";
|
||||
homepage = "https://github.com/owner/repo";
|
||||
license = licenses.mit; # Use actual license
|
||||
mainProgram = pname;
|
||||
platforms = platforms.all; # Or specific platforms
|
||||
};
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
- Use `#` for single-line comments
|
||||
- Place comments above the code they describe
|
||||
- Document non-obvious patches or workarounds (see manim-mcp-server for example)
|
||||
|
||||
## Adding New Packages
|
||||
|
||||
### 1. Create Package Directory
|
||||
```bash
|
||||
mkdir -p packages/<package-name>
|
||||
```
|
||||
|
||||
### 2. Choose the Right Builder
|
||||
|
||||
| Language | Builder |
|
||||
|----------|-------------------------------------------|
|
||||
| Python | `python3Packages.buildPythonApplication` |
|
||||
| Python | `stdenv.mkDerivation` with `makeWrapper` |
|
||||
| Go | `buildGoModule` |
|
||||
| Node.js | `buildNpmPackage` |
|
||||
| Rust | `rustPlatform.buildRustPackage` |
|
||||
|
||||
### 3. Create package.nix
|
||||
|
||||
See `packages/manim-mcp-server/package.nix` for a reference implementation.
|
||||
|
||||
### 4. Register the Package
|
||||
|
||||
Add to `packages/default.nix`:
|
||||
```nix
|
||||
new-mcp-server = pkgs.callPackage ./new-mcp-server/package.nix { };
|
||||
```
|
||||
|
||||
### 5. Build and Test
|
||||
```bash
|
||||
nix build .#<package-name>
|
||||
./result/bin/<package-name>
|
||||
```
|
||||
|
||||
## Git Conventions
|
||||
|
||||
### Commit Messages
|
||||
|
||||
- Use short, lowercase messages for simple changes: `fix`, `update`, `add`
|
||||
- Use sentence case for descriptive commits: `Add manim-mcp-server package`
|
||||
- Keep the first line under 72 characters
|
||||
|
||||
### What to Commit
|
||||
|
||||
- Package derivations (`package.nix` files)
|
||||
- Updates to `packages/default.nix`
|
||||
- Updates to `flake.nix` and `flake.lock`
|
||||
- Documentation updates
|
||||
|
||||
### What NOT to Commit
|
||||
|
||||
- `.envrc` (use `nix develop` instead)
|
||||
- `.direnv/` directory
|
||||
- Build artifacts (`result/`)
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Patching Source Files
|
||||
|
||||
When upstream code has hardcoded paths, use `substitute`:
|
||||
```nix
|
||||
substitute src/file.py $out/lib/${pname}/file.py \
|
||||
--replace-fail 'old-string' 'new-string'
|
||||
```
|
||||
|
||||
### Python Wrapper Pattern
|
||||
|
||||
For Python scripts without proper packaging:
|
||||
```nix
|
||||
let
|
||||
python = python3.withPackages (ps: with ps; [ mcp fastmcp ]);
|
||||
in
|
||||
stdenv.mkDerivation {
|
||||
# ...
|
||||
installPhase = ''
|
||||
makeWrapper ${python}/bin/python $out/bin/${pname} \
|
||||
--add-flags "$out/lib/${pname}/server.py"
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Set environment variables in wrappers using `--set`:
|
||||
```nix
|
||||
makeWrapper ${python}/bin/python $out/bin/${pname} \
|
||||
--set SOME_VAR "value"
|
||||
```
|
||||
Reference in New Issue
Block a user