Metadata-Version: 2.4
Name: chimeralang-mcp
Version: 0.7.2
Summary: ChimeraLang MCP Server — probabilistic types, consensus gates, and hallucination detection as Claude tools
Project-URL: Homepage, https://github.com/fernandogarzaaa/chimeralang-mcp
Project-URL: Repository, https://github.com/fernandogarzaaa/chimeralang-mcp
Project-URL: Issues, https://github.com/fernandogarzaaa/chimeralang-mcp/issues
Author-email: Fernando Garza <fernando@openchimera.dev>
License: MIT
License-File: LICENSE
Keywords: ai,chimeralang,claude,constraint-enforcement,hallucination-detection,llm-safety,mcp,probabilistic-types
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Provides-Extra: conformance
Requires-Dist: starlette>=0.37.0; extra == 'conformance'
Requires-Dist: uvicorn>=0.30.0; extra == 'conformance'
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: starlette>=0.37.0; extra == 'dev'
Requires-Dist: uvicorn>=0.30.0; extra == 'dev'
Provides-Extra: eval
Requires-Dist: pytest>=8.0.0; extra == 'eval'
Provides-Extra: sync
Requires-Dist: datasets>=2.20.0; extra == 'sync'
Requires-Dist: huggingface-hub>=0.23.0; extra == 'sync'
Description-Content-Type: text/markdown

# chimeralang-mcp

**Give Claude typed confidence, hallucination detection, and constraint enforcement as native MCP tools.**

ChimeraLang is a programming language built for AI cognition. This MCP server exposes its runtime as **44 tools** Claude can call during any conversation. No Anthropic permission needed, works today with Claude Desktop and Claude Code.

---

## Install

```bash
pip install chimeralang-mcp
# or
uvx chimeralang-mcp
```

### Development quick checks

```bash
pytest -q
python -m pip check
```

`pytest` is configured via `pyproject.toml` to include project root on `PYTHONPATH`.

For token counting internals, these optional environment variables are supported:

- `CHIMERA_TOKEN_CACHE_MAX_ENTRIES` (default `2048`) — bounds in-memory token count cache size.
- `CHIMERA_TOKEN_FALLBACK_LOG_INTERVAL_S` (default `60`) — throttles repeated fallback warning logs.

---

## Claude Desktop Setup

Add to your config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chimeralang": {
      "command": "uvx",
      "args": ["chimeralang-mcp"]
    }
  }
}
```

Or with a pip-installed version:

```json
{
  "mcpServers": {
    "chimeralang": {
      "command": "python",
      "args": ["-m", "chimeralang_mcp"]
    }
  }
}
```

Restart Claude Desktop. 44 ChimeraLang tools are now available.

---

## Tools

The core language/runtime tools are executable and deterministic. Several higher-level reasoning, safety, and cognition helpers are lightweight local heuristics intended for planning, triage, and guardrails rather than authoritative verification.

Most stateful tools accept an optional `namespace` and persist data to `~/.chimeralang_mcp` (or `CHIMERA_MCP_DATA_DIR`) so agents can carry memory, world state, traces, and cost history across sessions. The package also ships an embedded material pack plus offline CLI commands for `sync`, `build`, `status`, and `licenses`.

### Core Language

| Tool | What it does |
|---|---|
| `chimera_run` | Execute a `.chimera` program string |
| `chimera_typecheck` | Static type-check a `.chimera` program without executing |
| `chimera_prove` | Execute plus generate a Merkle-chain integrity proof |

### Confidence and Safety

| Tool | What it does |
|---|---|
| `chimera_confident` | Assert a value meets the `>= 0.95` confidence threshold |
| `chimera_explore` | Wrap a value as exploratory and explicitly allow uncertainty |
| `chimera_gate` | Collapse multiple candidates via consensus |
| `chimera_constrain` | Full constraint middleware on any tool result |
| `chimera_detect` | Hallucination and MCP security detection across range, dictionary, semantic, cross-reference, temporal, and confidence-threshold strategies |
| `chimera_safety_check` | Validate content against a safety policy and flag prompt-injection, tool-poisoning, token-theft, and oversharing patterns |
| `chimera_ethical_eval` | Evaluate an action against ethical principles |

### Reasoning and Cognition

| Tool | What it does |
|---|---|
| `chimera_plan_goals` | Decompose a high-level goal into ordered sub-goals |
| `chimera_causal` | Build and query a causal graph |
| `chimera_deliberate` | Heuristic multi-perspective deliberation with Jaccard similarity and divergence scoring |
| `chimera_quantum_vote` | Multi-agent consensus voting with contradiction detection |
| `chimera_metacognize` | Reflect on reasoning quality and compute calibration metrics |
| `chimera_self_model` | Maintain a persistent self-model of agent capabilities |
| `chimera_embodied` | Embodied reasoning simulation |
| `chimera_social` | Social reasoning and perspective modelling |
| `chimera_evolve` | Run fitness-ranked candidate selection across generations |
| `chimera_meta_learn` | Record adaptation events and retrieve meta-learning stats |
| `chimera_transfer_learn` | Map concepts across source and target domains |

### Knowledge and Memory

| Tool | What it does |
|---|---|
| `chimera_world_model` | Persistent namespace-scoped world model (key to value with confidence) |
| `chimera_knowledge` | Persistent namespace-scoped knowledge base (add, search, list) |
| `chimera_memory` | Persistent namespace-scoped memory store (store, recall by importance) |

### Provenance and Verification

| Tool | What it does |
|---|---|
| `chimera_claims` | Extract atomic claims from text or an envelope with claim typing plus hedge and abstention tags |
| `chimera_verify` | Verify claims against evidence with FEVER-style supported, contradicted, or insufficient-evidence verdicts |
| `chimera_provenance_merge` | Merge multiple result envelopes into one aggregated provenance object |
| `chimera_policy` | Apply reusable constraint profiles like `strict_factual`, `mcp_security`, and `research_factcheck` |
| `chimera_trace` | Inspect persisted result envelopes and trace history, including material-pack metadata |
| `chimera_materials` | Inspect bundled material packs, licenses, build status, and pinned source manifests |

### Token Budget, Cost, and Workflow

The token-efficiency stack now defaults to a deterministic, quantum-inspired compressor: it scores text spans by salience amplitude, boosts shared entities through entanglement, suppresses redundant spans through interference, and then "measures" the best units under a token budget. `chimera_optimize`, `chimera_compress`, `chimera_fracture`, and `chimera_csm` all accept `algorithm="classic|quantum"` and optional `focus` text so compression can stay task-aware instead of blindly deleting tokens.

| Tool | What it does |
|---|---|
| `chimera_compress` | Query-aware text compression with legacy rewrite fallback |
| `chimera_optimize` | Aggressive salience extraction for large text or code blobs |
| `chimera_fracture` | Full pipeline: optimize docs plus compress messages plus budget gate |
| `chimera_score` | Rank messages by importance for lossy compression decisions, with optional task focus |
| `chimera_budget` | Report current token usage against a budget |
| `chimera_cost_estimate` | Deterministic cost estimate for any supported model |
| `chimera_cost_track` | Record before and after compression events to the tracker |
| `chimera_dashboard` | Namespace-level cost intelligence summary |
| `chimera_csm` | Context Session Manager: optimize prompt, compress history, and propose a token budget |
| `chimera_budget_lock` | Lock and track an approved per-turn output budget |
| `chimera_mode` | Recommend a task-relevant subset of the tool inventory |
| `chimera_batch` | Execute multiple Chimera tools in a single MCP call |
| `chimera_summarize` | LLM-free extractive summarizer for long documents |

### Meta and Audit

| Tool | What it does |
|---|---|
| `chimera_audit` | Session-level call log, confidence summary, and persistent audit stats |

---

## What problem does this solve?

Claude's tool-use loop has no built-in mechanism for:

- **Confidence gating** - only proceed if confidence is above a threshold
- **Typed output contracts** - a result must satisfy a constraint before going downstream
- **Genuine consensus detection** - determine whether multi-path agreement is substantive
- **Hallucination signals** - structured detection rather than pure intuition
- **Trust propagation** - confidence and provenance should survive chained tool calls
- **Evidence-backed verification** - explicit claims checked against supplied evidence
- **Persistent reasoning state** - memory, world state, and traces carried across sessions
- **Cost intelligence** - token tracking and compression throughout long sessions

ChimeraLang provides a practical constraint layer between Claude and its tools. The language runtime is the strongest guarantee surface. The higher-level cognition and safety helpers are best treated as lightweight first-pass checks unless you pair them with stronger external evidence.

---

## Example prompts

**Gate a value before a critical action:**  
*"Before you submit that form, use `chimera_confident` to verify you're at least 0.95 confident the data is correct."*

**Consensus across reasoning paths:**  
*"Generate 3 different answers, then use `chimera_quantum_vote` to collapse to the most reliable one."*

**Hallucination scan on output:**  
*"After you get that search result, run `chimera_detect` with semantic strategy to check for absolute-certainty markers."*

**Full constraint pipeline:**  
*"Use `chimera_constrain` on that tool result with `min_confidence=0.85` and `detect_strategy=semantic`."*

**Evidence-backed fact checking:**  
*"Extract claims with `chimera_claims`, verify them against these sources with `chimera_verify`, then apply `chimera_policy` using `strict_factual`."*

**Trace and provenance inspection:**  
*"Merge the envelopes from those two tool calls with `chimera_provenance_merge`, then inspect the latest trace with `chimera_trace`."*

**Material-pack inspection and build flow:**  
*"List the bundled packs with `chimera_materials`, then run `chimeralang-mcp build` locally if you want generated JSON runtime and eval pack artifacts on disk."*

---

## ChimeraLang Quick Reference

### Variable Declaration

Both `val` and `let` are supported:

```chimera
val answer = Confident("Paris", 0.97)
let hypothesis = Explore("maybe dark matter is...", 0.4)
```

### Probabilistic Types

```chimera
emit Confident("verified fact", 0.97)
emit Explore("hypothesis", 0.60)
```

### Assertions

```chimera
assert Confident(0.78) > Confident(0.45)
```

### Gate Declaration

```chimera
gate verify(claim: Text) -> Converge<Text>
  branches: 3
  collapse: weighted_vote
  threshold: 0.80
  return claim
end
```

### Logical Operators

Both keyword and symbolic forms are supported:

```chimera
if a > 0.5 and b > 0.5
  emit Confident("both pass", 0.9)
end

if a > 0.5 && b > 0.5
  emit Confident("both pass", 0.9)
end
```

### Hallucination Detection

```chimera
detect temperature_check
  strategy: "range"
  on: temperature
  valid_range: [-50.0, 60.0]
  action: "flag"
end
```

### If / Else

```chimera
if confidence > 0.80
  emit Confident("high confidence result", 0.9)
else
  emit Explore("low confidence - needs review", 0.5)
end
```

### For Loop

```chimera
for item in items
  emit Explore(item, 0.6)
end
```

### Match

```chimera
match verdict
| "pass" => emit Confident("approved", 0.95)
| "fail" => emit Explore("rejected", 0.70)
| _      => emit Explore("unknown", 0.50)
end
```

---

## Changelog

### 0.6.0
- Add a deterministic quantum-inspired token compression engine with salience amplitude, entanglement boosts, redundancy interference, and budgeted measurement
- Make `chimera_optimize`, `chimera_compress`, `chimera_fracture`, and `chimera_csm` query-aware through optional `focus` input plus `classic|quantum` algorithm selection
- Upgrade `chimera_fracture` to return the actual optimized documents and compressed message artifacts instead of only aggregate stats
- Fix `TokenBudgetManager` singleton behavior so token-count caches are reused across tool calls

### 0.5.0
- Add a material-pack subsystem with pinned source manifests, pack builders, a loader, and offline `sync` / `build` / `status` / `licenses` CLI commands
- Add `chimera_materials` and wire pack metadata into claims, verification, policy, detect, safety, trace, and audit flows
- Upgrade claim extraction with pack-driven claim typing plus hedge and abstention tagging
- Upgrade verification to FEVER-style verdicts with evidence matches, taint-aware attack flags, and pack-version reporting
- Add MCP security policies, OWASP MCP Top 10 mappings, CI material builds, and an HTTP transport path for conformance workflows

### 0.4.0
- Add a unified result envelope model with confidence, provenance, transform history, claims, constraints, warnings, and metadata
- Persist namespace-scoped knowledge, memory, world model, self model, meta-learning history, traces, and cost tracking to disk
- Add `chimera_claims`, `chimera_verify`, `chimera_provenance_merge`, `chimera_policy`, and `chimera_trace`
- Expose evidence-backed verification and reusable policy application directly through MCP tools
- Add regression coverage for namespace persistence, claim extraction, verification, provenance merge, policy enforcement, and trace inspection

### 0.3.2
- Preserve structured JSON values through `chimera_confident`, `chimera_explore`, and `chimera_constrain` instead of stringifying them
- Fix multimodal message token estimation fallback so `chimera_cost_estimate`, `chimera_budget`, and `chimera_csm` do not undercount text-array content
- Make `chimera_fracture` stop dropping history once the budget is satisfied instead of over-pruning to the minimum message floor
- Fix `chimera_mode full` to report the real live tool inventory and align README documentation with the current 38-tool surface

### 0.2.7
- Fix `UnboundLocalError` in `chimera_cost_track` caused by `log` variable shadowing the module-level logger in the `chimera_audit` handler
- Add `let` as a keyword alias for `val` in variable declarations
- Add `&&` and `||` as lexer tokens (aliases for `and` and `or`)
- Expand tool count to 33 in the README

### 0.2.5
- Initial AGI component suite: causal reasoning, deliberation engine, quantum vote, safety layer, ethical reasoner
- Knowledge base, world model, session memory
- Cost tracking, budget management, dashboard
- Self-model and metacognition tools

---

## Links

- **ChimeraLang core:** [github.com/fernandogarzaaa/ChimeraLang](https://github.com/fernandogarzaaa/ChimeraLang)
- **OpenChimera:** [github.com/fernandogarzaaa/OpenChimera_v1](https://github.com/fernandogarzaaa/OpenChimera_v1)

---

## License

MIT (c) [Fernando Garza](https://github.com/fernandogarzaaa)
## Materials CLI

The wheel includes a compact curated core material pack. Larger corpora stay external and are only touched through manual CLI commands:

```bash
chimeralang-mcp status
chimeralang-mcp licenses
chimeralang-mcp sync
chimeralang-mcp build
```

- `status` reports bundled pack counts and whether generated artifacts already exist in `CHIMERA_MCP_DATA_DIR/materials`
- `licenses` prints the machine-readable source and bundle-policy report
- `sync` fetches current upstream metadata snapshots for the pinned GitHub and Hugging Face sources
- `build` writes normalized JSON manifests plus runtime and eval pack files to disk

The runtime MCP tools never fetch from the network. They only consume the bundled core pack and any already-generated local artifacts.

---
