Mpc Mcp Server

MPC — 亚稳态命题演算

亚稳态命题演算（MPC）引擎。 分析逻辑断言在多步推理中的热力学与物理可行性。与标准布尔逻辑不同，MPC 通过计算随时间维持前提的能量成本，检测认知漂移和结构冲突（k 态）。借助此工具，可严格验证复杂的主张序列能否在不陷入矛盾的情况下同时维持逻辑一致。

真值：c（已承诺）· s（已挂起）· k（冲突）· r（重置）

---

理论与背景

要成功使用此工具，了解 MPC 的理论基础会很有帮助。该框架将命题建模为置于潜在能量景观中的系统，而非瞬时且无代价的布尔状态。若要详细了解驱动此引擎的物理学、数学和逻辑，请查阅以下奠基性项目资料：

• 亚稳态命题演算（MPC）作为热力学扩展——第 1 部分
• 亚稳态命题演算（MPC）作为热力学扩展——第 2 部分
• 亚稳态命题演算（MPC）作为热力学扩展——第 3 部分

---

v0.3 新增内容

功能	详情
FastMCP	将底层 MCP 服务替换为 FastMCP，使工具定义更简洁，并提升客户端兼容性
五家提供商路由	Anthropic · Google · OpenAI · Kimi（Moonshot AI）· Ollama——均为一等支持
动态模型列表	实时查询各提供商的模型列表端点；缓存 TTL 为 5 分钟
零环境变量冲突	每家提供商都有独立变量：ANTHROPIC_API_KEY、GOOGLE_API_KEY、OPENAI_API_KEY、KIMI_API_KEY、OLLAMA_HOST
UI 中的提供商标签页	并排配置密钥，查看各提供商状态和模型数量
list_available_models 工具	新增 MCP 工具，用于动态发现模型
重试逻辑	临时错误最多重试 3 次，采用指数退避
/status + /env 端点	检查提供商运行状况和环境变量，不会暴露密钥值

---

提供商

提供商	SDK	密钥环境变量	备注
Anthropic	anthropic	ANTHROPIC_API_KEY	Claude claude-opus-4-6、claude-sonnet-4-6、Haiku
Google	google-generativeai	GOOGLE_API_KEY	Gemini 2.5 Pro、2.0 Flash、1.5
OpenAI	openai	OPENAI_API_KEY	GPT-4o、o1、o3-mini 等
Kimi	openai（兼容 OpenAI）	KIMI_API_KEY	Moonshot AI · moonshot.cn
Ollama	标准库 urllib	OLLAMA_HOST	本地模型，无需密钥

API 密钥按以下顺序解析：显式参数 → 环境变量 → .env 文件。任何提供商都不会读取其他提供商的密钥变量。

---

安装

# Core — all five providers included
pip install -e .

# Add QuTiP for exact partition function (Ising Hamiltonian)
pip install qutip

# Add NetKet for spin-glass ground-state solver (requires JAX)
pip install "jax[cpu]" netket

# Full stack
pip install -e ".[full]"

需要 Python ≥ 3.11。

---

快速开始

设置 API 密钥

# Any combination — only set what you have
export ANTHROPIC_API_KEY=sk-ant-…
export GOOGLE_API_KEY=AIza…
export OPENAI_API_KEY=sk-…
export KIMI_API_KEY=sk-…          # Moonshot AI key
export OLLAMA_HOST=http://localhost:11434   # default; omit if standard

也可以在浏览器 UI 中使用 Providers 标签页输入密钥，并将其保存到 .env。

启动服务

mpc-server

将启动：

• 通过标准输入输出运行的 MCP 服务（在 Claude Desktop 或任意 MCP 客户端中注册）
• 位于 http://localhost:7771 的 浏览器 UI

---

Claude Desktop 配置

{
  "mcpServers": {
    "mpc": {
      "command": "mpc-server",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-…",
        "GOOGLE_API_KEY": "AIza…",
        "OPENAI_API_KEY": "sk-…",
        "KIMI_API_KEY": "sk-…"
      }
    }
  }
}

---

MCP 工具

工具	描述	是否调用 API？
compile_text	完整的 MPC 分析：假设、阶段、挫折矩阵、自由能（QuTiP）、自旋玻璃基态、定理 6.1 界限	✓
compile_sequence	带实体账本的多步追踪——跟踪认知漂移和 η_i 累积	✓
read_claims	为每条主张分配阶段（c/s/k/r）并说明理由	✓
budget_estimate	定理 6.1 N_max = O(√(2E*/αε_min d_avg))——纯算术计算	✗
list_available_models	实时查看全部五家提供商的模型目录	✗（缓存）

所有工具都接受可选参数 provider_api_key；省略时会自动读取环境变量。

---

Python API

import mpc_core

# Full analysis — Anthropic (default)
result = mpc_core.compile("Your text here…", api_key="sk-ant-…")

# Google Gemini
result = mpc_core.compile("…", model="gemini-2.0-flash", api_key="AIza…")

# OpenAI
result = mpc_core.compile("…", model="gpt-4o", api_key="sk-…")

# Kimi (Moonshot AI)
result = mpc_core.compile("…", model="moonshot-v1-32k", api_key="sk-…")

# Local Ollama (no key needed)
result = mpc_core.compile("…", model="llama3:8b")

print(result.energy_model.free_energy)      # F = -kT ln Z
print(result.ground_state.energy)           # Ising ground-state energy
print(result.ground_state.stable_ids)       # most compatible hypothesis subset
print(result.analytical_summary)

# Per-claim phase assignment
phases = mpc_core.read_claims(
    ["All ravens are black.", "Some ravens are albino."],
    api_key="sk-ant-…",
    model="claude-sonnet-4-6",
)

# Budget theorem (no API call)
est = mpc_core.budget_estimate(N=8, d_avg=2.5, epsilon_min=1.2)
print(est.interpretation)

# Multi-step trace with Entity Ledger
seq = mpc_core.compile_sequence(
    ["Step 1 text…", "Step 2 text…", "Step 3 text…"],
    api_key="sk-ant-…",
)

# Dynamic model listing
from mpc_core.providers import list_models, ProviderID
models = list_models(ProviderID.ANTHROPIC, "sk-ant-…")

# Free-energy surface (no API call)
from mpc_core.thermodynamics import free_energy_surface
surface = free_energy_surface(my_epsilon_matrix, T_range=(0.2,5), E_star_range=(2,40))
# surface["F"][T_index][E_star_index] → F value

---

浏览器 UI — 标签页

标签页	描述
分析文本	完整的 MPC 分析，包含假设卡片、热力学信息栏（Z、F、S）、基态框
读取主张	每行一条主张 → 即时分配阶段
3D 自由能	交互式 Plotly F(T, E*) 曲面，带有定理 6.1 等高线 N_max
能量景观	带预算／温度滑块的动画 2D 画布
兼容性矩阵	成对 ε_ij 挫折表
预算计算器	定理 6.1 N_max——无需 API 密钥
历史热力图	推理追踪中的 η_i 累积情况（附录 V）
提供商	API 密钥配置、各提供商状态和模型数量

---

HTTP API（localhost:7771）

方法	路径	描述
GET	/	浏览器 UI（index.html）
GET	/models	使用环境变量密钥获取模型目录
POST	/models	使用调用方提供的密钥刷新目录
GET	/env	查看已设置的环境变量（值已隐藏）
POST	/status	提供商连接状态检查
POST	/setenv	将密钥保存到 .env
POST	/	MPC 操作（compile、compile_sequence、read_claims、budget_estimate、free_energy_surface、ground_state）

---

测试

# Arithmetic tests (no API key required)
pytest tests/ -v

# Live API tests — any provider combination
ANTHROPIC_API_KEY=sk-ant-…  pytest tests/ -v
GOOGLE_API_KEY=AIza…        pytest tests/ -v
OPENAI_API_KEY=sk-…         pytest tests/ -v
KIMI_API_KEY=sk-…           pytest tests/ -v

---

架构

mpc_core/
  providers.py     NEW v0.3 — ProviderID enum, per-provider key resolution,
                   dynamic model listing with TTL cache, all_models_catalogue()
  router.py        REWRITTEN — five-backend dispatch, retry logic, auth-error fast-fail
  compiler.py      compile() · read_claims() · budget_estimate() · compile_sequence()
  entity_ledger.py Cross-step entity registry (four-layer pipeline)
  thermodynamics.py QuTiP partition function · NetKet spin-glass · free_energy_surface()
  json_repair.py   Best-effort repair of truncated LLM JSON
  models.py        MPCResult dataclass hierarchy

mpc_server/
  server.py        REWRITTEN — FastMCP application + HTTP UI proxy (port 7771)
                   New endpoints: GET /env, POST /status, POST /models

static/
  index.html       REWRITTEN — provider selector tabs, per-provider key inputs,
                   dynamic model dropdowns, /status integration

---

路线图

• v0.1 ✓ 核心编译器、MCP 服务、参考 UI
• v0.2 ✓ 多后端路由 · QuTiP · NetKet · 3D Plotly · 历史热力图
• v0.3 ✓ FastMCP · 五家提供商 · 动态模型列表 · 提供商 UI · 重试逻辑
• v0.4 定理 6.1 的谱拉普拉斯扩展、考虑社区结构的 N_max 界限
• v0.5 流式分析；逐步显示各假设的 η_i 差异

---

许可证

MIT