Enabling the MCP Server¶

The ai-rulez MCP (Model Context Protocol) server allows your AI assistant to programmatically and safely interact with your .ai-rulez/ configuration. Since V4 uses a file-based approach with inline MCP configuration, you define servers directly in config.toml, and the MCP server provides read-only access for AI assistants to generate outputs and validate your configuration.

You do not need to start the server manually. Your AI assistant will start it automatically based on the configuration you provide.

Configuration Examples¶

To enable the server, add one of the following snippets to your AI assistant's configuration file (e.g., Cursor's settings.json), or define it inline in .ai-rulez/config.toml.

Using `npx` (Recommended for Node.js users)¶

This method ensures you are always using the latest version of ai-rulez without needing to install it globally.

{
  "mcp_servers": {
    "ai-rulez": {
      "command": "npx",
      "args": ["-y", "ai-rulez@latest", "mcp"]
    }
  }
}

Using `uvx` (Recommended for Python users)¶

This method uses uvx to run ai-rulez in an ephemeral environment.

{
  "mcp_servers": {
    "ai-rulez": {
      "command": "uvx",
      "args": ["ai-rulez", "mcp"]
    }
  }
}

Using a Local Go Installation¶

If you have installed ai-rulez locally with go install.

{
  "mcp_servers": {
    "ai-rulez": {
      "command": "ai-rulez",
      "args": ["mcp"]
    }
  }
}

Inline in `config.toml` (V4 Recommended)¶

V4 supports defining MCP servers directly in your .ai-rulez/config.toml:

[[mcp_servers]]
name = "ai-rulez"
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]

[[mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your-github-token" }

Server Capabilities¶

When enabled, the MCP server provides your AI assistant with access to your configuration and CRUD operations. The server supports:

Read Configuration: Inspect rules, context, skills, profiles, and presets
Generate Outputs: Programmatically trigger generation of tool-specific files
Validate Configuration: Check configuration validity and report errors
CRUD Operations: Create, read, update, and delete domains, rules, context, skills, includes, and profiles

The MCP server enables AI assistants to:

Understand your setup by reading configuration and content files
Modify configuration programmatically via CRUD tools
Generate outputs after changes
Validate changes before committing

This approach ensures your configuration remains auditable and version-controlled, while allowing AI assistants to help you manage it efficiently.

Typical Workflow¶

With Your Editor¶

Edit files directly in .ai-rulez/:

# Edit rules, context, skills, or config.yaml
vim .ai-rulez/rules/code-quality.md

Use MCP server (via AI assistant) to generate:
```
ai-rulez generate
```

Commit changes:

git add .ai-rulez/ CLAUDE.md .cursor/
git commit -m "docs: update AI guidelines"

With Claude CLI¶

If using the Claude CLI with the ai-rulez MCP server, you can ask Claude to help:

"Review my .ai-rulez/ configuration and suggest improvements"
"Generate outputs for my new rules"
"Validate that my profiles are correct"
"Create a new backend domain and add database rules"
"Add an include from our shared rules repository"

The server provides Claude with access to read and modify your configuration, while you maintain full control over final decisions.

MCP CRUD Tools Reference¶

The ai-rulez MCP server exposes 22 CRUD tools for programmatic configuration management. These tools allow AI assistants to create, read, update, and delete configuration elements.

Domain Tools¶

`create_domain`¶

Create a new domain with subdirectories for rules, context, and skills.

Parameters: - name (required, string): Domain name (alphanumeric and underscores, 1-50 characters) - description (optional, string): Description of the domain

Response:

{
  "success": true,
  "operation": "create_domain",
  "name": "backend",
  "path": ".ai-rulez/domains/backend",
  "message": "Domain created successfully"
}

Example:

Create a domain called "backend" for backend services

`delete_domain`¶

Delete a domain and all its contents.

Parameters: - name (required, string): Domain name to delete

Response:

{
  "success": true,
  "operation": "delete_domain",
  "name": "backend",
  "message": "Domain deleted successfully"
}

`list_domains`¶

List all domains in the .ai-rulez/ directory.

Parameters: (none)

Response:

{
  "success": true,
  "operation": "list_domains",
  "domains": [
    {
      "name": "backend",
      "path": ".ai-rulez/domains/backend",
      "rulesCount": 3,
      "contextCount": 2,
      "skillsCount": 1
    }
  ],
  "count": 1
}

Rule Tools¶

`create_rule`¶

Create a new rule file with optional YAML frontmatter.

Parameters: - name (required, string): Rule filename without .md extension - content (optional, string): Markdown content with optional YAML frontmatter - domain (optional, string): Domain name (if not specified, creates in root) - priority (optional, string): Priority level - critical, high, medium, low. Default: medium - targets (optional, array): Target providers (e.g., ["claude", "cursor"])

Response:

{
  "success": true,
  "operation": "create_rule",
  "path": ".ai-rulez/rules/code-quality.md",
  "name": "code-quality",
  "domain": null,
  "message": "Rule created successfully"
}

`update_rule`¶

Update an existing rule file.

Parameters: - name (required, string): Rule filename without .md extension - content (required, string): New markdown content - domain (optional, string): Domain name - priority (optional, string): Priority level - targets (optional, array): Target providers

Response: Same as create_rule

`delete_rule`¶

Delete a rule file.

Parameters: - name (required, string): Rule filename without .md extension - domain (optional, string): Domain name

Response:

{
  "success": true,
  "operation": "delete_rule",
  "name": "code-quality",
  "domain": null,
  "message": "Rule deleted successfully"
}

`list_rules`¶

List all rules in the root or a specific domain.

Parameters: - domain (optional, string): Domain name (lists root rules if not specified)

Response:

{
  "success": true,
  "operation": "list_rules",
  "domain": null,
  "rules": [
    {
      "name": "code-quality",
      "path": ".ai-rulez/rules/code-quality.md",
      "priority": "high",
      "targets": ["claude", "cursor"]
    }
  ],
  "count": 1
}

Context Tools¶

`create_context`¶

Create a new context file (documentation/reference material).

Parameters: - name (required, string): Context filename without .md extension - content (optional, string): Markdown content with optional YAML frontmatter - domain (optional, string): Domain name - priority (optional, string): Priority level - targets (optional, array): Target providers

Response: Similar to create_rule

`update_context`¶

Update an existing context file.

Parameters: Same as create_context, with content as required

Response: Similar to create_rule

`delete_context`¶

Delete a context file.

Parameters: - name (required, string): Context filename without .md extension - domain (optional, string): Domain name

Response: Similar to delete_rule

`list_context`¶

List all context files in the root or a specific domain.

Parameters: - domain (optional, string): Domain name

Response: Similar to list_rules, with "context" key instead of "rules"

Skill Tools¶

`create_skill`¶

Create a new skill file (AI prompt/expert definition).

Parameters: - name (required, string): Skill filename without .md extension - content (optional, string): Markdown content with optional YAML frontmatter - domain (optional, string): Domain name - priority (optional, string): Priority level - targets (optional, array): Target providers

Response: Similar to create_rule

`update_skill`¶

Update an existing skill file.

Parameters: Same as create_skill, with content as required

Response: Similar to create_rule

`delete_skill`¶

Delete a skill file.

Parameters: - name (required, string): Skill filename without .md extension - domain (optional, string): Domain name

Response: Similar to delete_rule

`list_skills`¶

List all skill files in the root or a specific domain.

Parameters: - domain (optional, string): Domain name

Response: Similar to list_rules, with "skills" key instead of "rules"

Include Tools¶

`add_include`¶

Add a new include source (git URL or local path) to the configuration.

Parameters: - name (required, string): Include name (unique identifier) - source (required, string): Git URL (https://github.com/org/repo) or local path (./packages/shared) - path (optional, string): Path within git repository where .ai-rulez/ content is located - ref (optional, string): Git reference - branch, tag, or commit hash (git sources only). Default: main - include (optional, array): Content types to include - rules, context, skills, mcp - merge_strategy (optional, string): Merge strategy - default, override, append - install_to (optional, string): Installation target path in .ai-rulez/

Response:

{
  "success": true,
  "operation": "add_include",
  "name": "corporate-rules",
  "source": "https://github.com/myorg/shared-rules",
  "message": "Include added successfully"
}

`remove_include`¶

Remove an include source from the configuration.

Parameters: - name (required, string): Include name to remove

Response:

{
  "success": true,
  "operation": "remove_include",
  "name": "corporate-rules",
  "message": "Include removed successfully"
}

`list_includes`¶

List all include sources in the configuration.

Parameters: (none)

Response:

{
  "success": true,
  "operation": "list_includes",
  "includes": [
    {
      "name": "corporate-rules",
      "source": "https://github.com/myorg/shared-rules",
      "ref": "main",
      "path": ".ai-rulez",
      "mergeStrategy": "default"
    }
  ],
  "count": 1
}

Installed Skill Tools¶

`install_skill`¶

Install a named skill from a git repository or local path.

Parameters: - name (required, string): Skill name (unique identifier) - source (required, string): Git URL or local filesystem path - path (optional, string): Path within repo to skill directory (defaults to skills/<name>) - ref (optional, string): Git reference (branch, tag, commit)

Response:

{
  "success": true,
  "operation": "install_skill",
  "name": "kreuzberg",
  "source": "https://github.com/kreuzberg-dev/kreuzberg",
  "message": "Skill installed successfully"
}

`uninstall_skill`¶

Remove an installed skill from the configuration.

Parameters: - name (required, string): Skill name to remove

Response:

{
  "success": true,
  "operation": "uninstall_skill",
  "name": "kreuzberg",
  "message": "Skill uninstalled successfully"
}

`list_installed_skills`¶

List all installed skills.

Parameters: None

Response:

{
  "success": true,
  "operation": "list_installed_skills",
  "installed_skills": [
    {
      "Name": "kreuzberg",
      "Source": "https://github.com/kreuzberg-dev/kreuzberg",
      "Path": "skills/kreuzberg",
      "Ref": "",
      "Type": "git"
    }
  ],
  "count": 1
}

Profile Tools¶

`add_profile`¶

Create a new profile with a set of domains.

Parameters: - name (required, string): Profile name (unique identifier) - domains (required, array): List of domain names to include in the profile

Response:

{
  "success": true,
  "operation": "add_profile",
  "name": "full",
  "domains": ["backend", "frontend", "qa"],
  "message": "Profile added successfully"
}

`remove_profile`¶

Remove a profile from the configuration.

Parameters: - name (required, string): Profile name to remove

Response:

{
  "success": true,
  "operation": "remove_profile",
  "name": "staging",
  "message": "Profile removed successfully"
}

`set_default_profile`¶

Set a profile as the default for generation.

Parameters: - name (required, string): Profile name to set as default

Response:

{
  "success": true,
  "operation": "set_default_profile",
  "name": "full",
  "message": "Default profile set successfully"
}

`list_profiles`¶

List all profiles in the configuration.

Parameters: (none)

Response:

{
  "success": true,
  "operation": "list_profiles",
  "profiles": [
    {
      "name": "full",
      "domains": ["backend", "frontend", "qa"],
      "isDefault": true
    },
    {
      "name": "backend",
      "domains": ["backend", "qa"],
      "isDefault": false
    }
  ],
  "count": 2
}

Common MCP Workflows¶

Creating a Domain with Rules¶

User: "Create a backend domain and add a database standards rule"

MCP Tool Sequence:
1. create_domain(name: "backend", description: "Backend services")
2. create_rule(name: "database-standards", domain: "backend", priority: "high", content: "...")
3. generate_outputs() - regenerate configurations

Adding an External Include¶

User: "Add our corporate rules from GitHub"

MCP Tool Sequence:
1. add_include(name: "corporate", source: "https://github.com/myorg/rules", ref: "main")
2. validate_config() - check if include is valid
3. generate_outputs() - regenerate with included content

Setting Up Team Profiles¶

User: "Create backend and frontend profiles for our team separation"

MCP Tool Sequence:
1. create_domain(name: "backend")
2. create_domain(name: "frontend")
3. add_profile(name: "backend", domains: ["backend"])
4. add_profile(name: "frontend", domains: ["frontend"])
5. set_default_profile(name: "backend")
6. generate_outputs()

Bulk Content Creation¶

User: "Add security rules to the backend domain"

MCP Tool Sequence:
1. create_rule(name: "authentication", domain: "backend", content: "...")
2. create_rule(name: "encryption", domain: "backend", content: "...")
3. create_context(name: "security-architecture", domain: "backend", content: "...")
4. validate_config()
5. generate_outputs()

Enabling the MCP Server¶

Configuration Examples¶

Using npx (Recommended for Node.js users)¶

Using uvx (Recommended for Python users)¶

Using a Local Go Installation¶

Inline in config.toml (V4 Recommended)¶

Server Capabilities¶

Typical Workflow¶

With Your Editor¶

With Claude CLI¶

MCP CRUD Tools Reference¶

Domain Tools¶

create_domain¶

delete_domain¶

list_domains¶

Rule Tools¶

create_rule¶

update_rule¶

delete_rule¶

list_rules¶

Context Tools¶

create_context¶

update_context¶

delete_context¶

list_context¶

Skill Tools¶

create_skill¶

update_skill¶

delete_skill¶

list_skills¶

Include Tools¶

add_include¶

remove_include¶

list_includes¶

Installed Skill Tools¶

install_skill¶

uninstall_skill¶

list_installed_skills¶

Profile Tools¶

add_profile¶

remove_profile¶

set_default_profile¶

list_profiles¶

Common MCP Workflows¶

Creating a Domain with Rules¶

Adding an External Include¶

Setting Up Team Profiles¶

Bulk Content Creation¶

Using `npx` (Recommended for Node.js users)¶

Using `uvx` (Recommended for Python users)¶

Inline in `config.toml` (V4 Recommended)¶

`create_domain`¶

`delete_domain`¶

`list_domains`¶

`create_rule`¶

`update_rule`¶

`delete_rule`¶

`list_rules`¶

`create_context`¶

`update_context`¶

`delete_context`¶

`list_context`¶

`create_skill`¶

`update_skill`¶

`delete_skill`¶

`list_skills`¶

`add_include`¶

`remove_include`¶

`list_includes`¶

`install_skill`¶

`uninstall_skill`¶

`list_installed_skills`¶

`add_profile`¶

`remove_profile`¶

`set_default_profile`¶

`list_profiles`¶