Metadata-Version: 2.4
Name: character-mcp
Version: 0.3.4
Summary: Filesystem-backed character data server for MCP clients
Author-email: Gert Schepens <gert@dgtl.be>
License: MIT License
        
        Copyright (c) 2026 Gert Schepens
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/DigitalGert/character-mcp
Project-URL: Source, https://gitlab.com/DigitalGert/character-mcp
Project-URL: Bug Tracker, https://gitlab.com/DigitalGert/character-mcp/-/issues
Keywords: mcp,ai,character,worldbuilding,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.23
Requires-Dist: mcp>=1.27.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# 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](https://openclaw.dev), 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:
```json
{"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:

```bash
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](https://gitlab.com/DigitalGert/character-mcp/-/blob/main/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

```bash
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:

```bash
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

```bash
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):

```json
{
  "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:
```json
"command": "/home/you/character-mcp-venv/bin/character-mcp-server"
```

### OpenClaw

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

```json
{
  "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](#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
