Soul MCP Server

What AntonioTF5/soul-mcp-server MCP server does

AntonioTF5/soul-mcp-server MCP server exposes three operations for the SOUL.md format. It can check whether a .soul.md file conforms to the SOUL.md schema, create a starter file for a new agent, and estimate how complete an existing file is.

The server is aimed at agent identity files that describe characteristics such as personality, voice, values, and behavioral constraints. It works through MCP, so an MCP client can invoke these operations from a conversational workflow instead of requiring a separate command-line validation step.

How it works

The validation and scoring tools accept a file path. validate_soul_file checks the referenced file against the schema and returns JSON containing a pass indicator, the detected name and version, and any validation errors. score_soul_file examines the optional fields and returns a numeric score from 0 to 100, along with counts or lists for filled, missing, and total fields.

generate_soul_template does not require an existing file path. Provide an agent name and, optionally, an array of domain keywords. The result is a ready-to-edit SOUL file returned as a string. For example, keywords related to carbon capture can seed a template for a climate-focused agent.

Setup and configuration

The README shows a local stdio configuration for Claude Desktop. Add an MCP server entry to claude_desktop_config.json and use npx to run the soul-mcp-server package:

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

After restarting Claude Desktop, the three tools should be available. The documented macOS configuration path is ~/Library/Application Support/Claude/claude_desktop_config.json. The setup instructions do not specify environment variables, API keys, or other credentials.

Tools and capabilities

• validate_soul_file: accepts a required path string and reports schema validation status, file name, version, and errors.
• generate_soul_template: accepts a required name string and optional keywords string array, then returns starter file content.
• score_soul_file: accepts a required path string and reports a 0–100 completeness score plus filled, missing, and total field information.

The tools can be used to validate an existing identity file, create an initial draft, or identify unfilled optional sections before further editing. The project also references the separate SOUL.md specification, example soul files, and a CLI validator that can operate without Claude; those are related resources rather than capabilities described for this MCP server.

Limitations and notes

AntonioTF5/soul-mcp-server MCP server is documented for validation, template generation, and completeness scoring. The material does not describe tools for deploying an agent, hosting a file, editing a file in place, or serving a live agent subdomain. Template generation returns content as a string, so the client or user must handle saving or editing that output.

A completeness score reflects how many optional fields are filled; it is not described as a measure of writing quality, behavioral correctness, or runtime agent performance. Validation depends on the referenced file path being available to the local server process. The README identifies the project as MIT-licensed and says it can be used from Claude Desktop or another MCP-compatible client.