mcpField
S
soul-mcp-server

soul-mcp-server

Local
github.com/AntonioTF5AI & Agents2Updated 28w ago
Repository

About soul-mcp-server

soul-mcp-server provides MCP tools for validating and creating SOUL.md agent identity files. It is for people defining agent identities, with schema checks, completeness scoring, and starter templates available from Claude Desktop or other MCP clients.

Key features

  1. 01Validate `.soul.md` files against the schema
  2. 02Generate editable identity templates
  3. 03Score file completeness from optional fields

Use cases

  1. 01Check a SOUL.md file for schema errors
  2. 02Create a starter identity file for an agent
  3. 03Find missing optional fields in an identity file

MCP support

Exposes three tools to MCP clients: `validate_soul_file`, `generate_soul_template`, and `score_soul_file`.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "antoniotf5-soul": {
      "command": "npx",
      "args": [
        "-y",
        "soul-mcp-server"
      ]
    }
  }
}
Run commandnpx -y soul-mcp-server

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmsoul-mcp-server1.0.0

Tools

3

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
pathstringYesPath to the .soul.md file to validate.

Details

From the project README

soul-mcp-server

License: MIT

MCP server for SOUL.md — validate and generate soul files directly from Claude Desktop or any MCP-compatible client.

Built for Agenturo — the reference SOUL.md implementation. Deploy your soul file as a live agent on your own subdomain.

30-second setup

Add this to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "soul-md-cli": {
      "command": "npx",
      "args": ["soul-mcp-server"]
    }
  }
}

Restart Claude Desktop. The three soul tools will appear in your tool list.

Tools

validate_soul_file

Validates a .soul.md file against the SOUL.md schema.

Parameters:

  • path (string, required) — path to the soul file

Returns: JSON with pass boolean, name, version, and errors array.

Example prompt:

"Validate my soul file at ~/agents/marcus.soul.md"

generate_soul_template

Generates a starter .soul.md for a given agent name and keywords.

Parameters:

  • name (string, required) — the agent's name
  • keywords (string[], optional) — domain keywords to seed the template

Returns: A ready-to-edit soul file as a string.

Example prompt:

"Generate a soul template for a climate scientist who specializes in carbon capture"

score_soul_file

Returns a completeness score (0–100) based on how many optional fields are filled.

Parameters:

  • path (string, required) — path to the soul file

Returns: JSON with score, filled, missing, and total.

Example prompt:

"Score my agent at ~/agents/startup-advisor.soul.md and tell me what's missing"

Spec & examples

Full specification: soul-spec

Curated community soul files: awesome-soul-files

CLI validator (no Claude required): soul-md-cli

MIT License. Created by Anton Agafonov.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.