character-mcp 0.3.4

Filesystem-backed character data server for MCP clients

Character MCP

Date: 2026-04-19
Status: Packaged Install Working, Debug Period Active

Overview

Character MCP is a server that exposes structured character, place, and object data to any MCP-compatible client. Originally built for OpenClaw, it works with Claude, Cursor, or any other MCP host.

This repository is not the live character database. It produces an installable package through GitLab CI. Real character data lives outside this repo and is mounted or configured at runtime.

The design goal is simple:

• keep the authoritative data human-editable
• keep the MCP contract narrow and predictable for agents
• keep the package code separate from user-owned data
• keep binary assets and personal data out of the release repo by default
• allow controlled writes only through explicit, validated tool paths

Current Features

• File-based entity store with entity.yaml plus markdown facets
• Entity types: character, place, object
• JSON Schema validation and type-aware integrity checks, including thin/placeholder facet warnings
• Read tools for summaries, facets, relationships, related entities, doctor, and rescan
• Guarded write tools for entity creation and narrow updates, with stricter place/object creation rules
• Broad character bucket facets like wardrobe and rituals are rejected at write time
• Dataset cleanup tool for quarantining orphan entity directories and pruning stale facet references
• Backup + validate + rollback write safety model
• Polling watcher for automatic rescans
• FastMCP server adapter compatible with any MCP client
• Tool-call trace file for auditing MCP usage
• Agent binding support for linking characters to named agents in your MCP client config (OpenClaw agent ID validation built-in)
• Guided character intake with draft creation, resumable next-step guidance, intake status, batch answer application, optional place/object creation, completion summaries, empty-dataset detection, guided import of already-known characters, and a dedicated proposed-identity facet for tentative framing
• Visual consistency metadata for canonical image refs, preferred image models, seeds, prompt notes, and LoRA/training-prep refs
• Entity summaries include a related_entities manifest so the AI sees all linked entities without a separate call
• Non-character entity responses (get_entity_summary, get_entity_facet) include a character_essentials block from the owning character — prevents identity drift during image generation
• Doctor checks for misplaced entity-type data: location prose in character facets, object details in character prose, and place/object entities with no character referencing them
• Optional debug logging to ~/.character-mcp/debug.log (ndjson, rotating) for auditing which tools the AI calls
• Safe local sample dataset for development and testing

MCP Tool Surface

Read tools

• get_dataset_status
• list_entities
• get_entity_summary
• list_entity_facets
• get_entity_facet
• list_entity_relationships
• get_related_entities
• get_visual_profile
• doctor_entity_index
• cleanup_dataset
• rescan_entities
• get_character_intake_status
• get_character_intake_next_step
• suggest_next_character_questions
• get_character_gap_report
• get_character_agent_binding

Write tools

• initialize_character_root
• create_entity
• start_character_intake
• start_existing_character_import
• apply_character_intake_answers
• link_character_agent
• update_entity_yaml
• write_entity_facet
• add_relationship
• append_entity_alias
• add_asset_reference
• update_visual_profile

These are intentionally narrow. The server does not support delete operations, arbitrary file mutation, or binary asset writes.

Facet Granularity

Character facets should be narrow and retrievable. Prefer one file per question the agent might reasonably ask.

Prefer:

• outfit-team-hoodie
• outfit-bjj
• ritual-morning-espresso
• ritual-evening-decompression

Avoid broad buckets like:

• wardrobe
• rituals
• rituals-and-wardrobe

If one file starts bundling multiple distinct outfits, rituals, or modes, split it. That keeps MCP retrieval targeted and reduces accidental overfetching.

For character entities, known broad bucket facets like wardrobe and rituals are now rejected at write time rather than accepted and warned about later.

Configuration

All configuration is via environment variables set in your MCP client config (e.g. claude_desktop_config.json):

Variable	Default	Purpose
CHARACTER_MCP_ROOT	(required)	Path to your character dataset
CHARACTER_MCP_TRANSPORT	stdio	Transport: stdio or sse
CHARACTER_MCP_WATCH	0	Set to 1 to auto-reload on file changes
CHARACTER_MCP_WATCH_INTERVAL	1.0	Seconds between watch polls
CHARACTER_MCP_OPENCLAW_CONFIG	(none)	Path to openclaw.json for agent ID validation (OpenClaw-specific, optional)
CHARACTER_MCP_DEBUG_LOG	0	Set to 1 to enable debug logging
CHARACTER_MCP_LOG_LEVEL	info	Log detail level: info or debug

When CHARACTER_MCP_DEBUG_LOG=1, every tool call is appended as a JSON object to ~/.character-mcp/debug.log (ndjson format, rotating at 5MB, 2 backups). At info level each entry includes timestamp, tool name, arguments, duration, and a result size hint. At debug level the full result is also included.

Example:

{"ts": "2026-04-19T17:00:00Z", "tool": "get_entity_summary", "args": {"entity_id": "dara"}, "duration_ms": 4.2, "result_hint": {"type": "dict", "related_entities_count": 3}}

Empty Dataset and Existing-Character Flow

Character MCP can now detect an empty character root and help the host start cleanly.

Current behavior:

• get_dataset_status reports whether the configured root exists, whether it is initialized, whether it is effectively empty, and what the next comfortable setup actions are
• initialize_character_root creates the basic characters/, places/, and objects/ folders plus a starter README.md
• start_existing_character_import creates a draft character tagged for import and frames the rest of the work as gradual confirmation of recalled knowledge rather than blind freeform writes
• new linked place and object entities now require a real summary plus non-placeholder profile.md content; stub shells are rejected instead of silently accepted

This is the basis for a welcome flow where an empty install can offer:

• initialize the dataset
• start a new character
• add someone the model already knows from context, with explicit confirmation before storing that knowledge

Local Development

To run the server against the bundled sample dataset during development:

uv run character-mcp-server
# or
python -m character_mcp.server

Set CHARACTER_MCP_ROOT to point at any character dataset directory. The build/sample-data/characters_root directory in this repo is a safe scratch dataset for testing.

Roadmap

The living roadmap is in ROADMAP.md.

The active product direction:

1. guided character intake expansion
2. deeper visual/reference workflows on top of the new visual profile support
3. gap detection and next-step guidance
4. packaging and install flow

Current Rough Edges

• import and intake quality can still drift semantically even when the writes are structurally valid
• linked entities can still be too thin if the model does not have enough grounded detail

Installation

From the GitLab Package Registry

pip install character-mcp \
  --index-url https://gitlab.com/api/v4/projects/DigitalGert%2Fcharacter-mcp/packages/pypi/simple

Install into a dedicated venv to keep it isolated from other tools:

python3 -m venv ~/character-mcp-venv
~/character-mcp-venv/bin/pip install character-mcp \
  --index-url https://gitlab.com/api/v4/projects/DigitalGert%2Fcharacter-mcp/packages/pypi/simple

From source

git clone https://gitlab.com/DigitalGert/character-mcp.git
cd character-mcp
pip install -e .

Client Configuration

Set CHARACTER_MCP_ROOT to the directory containing your characters/, places/, and objects/ folders.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "character-mcp": {
      "command": "character-mcp-server",
      "env": {
        "CHARACTER_MCP_ROOT": "/path/to/your/characters"
      }
    }
  }
}

If installed into a venv, use the full path to the binary:

"command": "/home/you/character-mcp-venv/bin/character-mcp-server"

OpenClaw

In ~/.openclaw/openclaw.json under mcp.servers:

{
  "mcp": {
    "servers": {
      "character-mcp": {
        "command": "/home/you/character-mcp-venv/bin/character-mcp-server",
        "args": [],
        "env": {
          "CHARACTER_MCP_ROOT": "/path/to/your/characters",
          "CHARACTER_MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Generic MCP client

Any client that supports stdio MCP servers needs:

• Command: character-mcp-server (or full venv path)
• Environment: CHARACTER_MCP_ROOT=/path/to/your/characters

See the Configuration section for all available environment variables.

Build and Release Model

GitLab CI runs on every push: tests, builds the wheel, and smoke-tests the install. On version tags (v0.3.x), it also publishes to the GitLab Package Registry and creates a release entry.

Artifacts from non-tagged builds are kept for 30 days and accessible from the pipeline's build job if you need a specific commit's build.

Non-Goals

This project is not, for now:

• a semantic search engine
• a digital asset manager
• a hosted multi-user database
• a repo for personal production character data