veriscope-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeriScope Sovereign Harbor
+
+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.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# VeriScope MCP Server (@veriscope/mcp-server)
+
+> **VeriScope** is a sovereign cryptographic bibliographic index and citation verification engine for AI Agents. It anchors AI Task Planners in verified scholarly editions across 24 disciplines with **exact chapter coordinates**, **verbatim fair-use excerpts (<=300 chars)**, **64-bit SHA-256 edition hashes**, and **Ed25519 tamper-proof digital receipts (`vsk_sig`)**.
+
+[![MCP Standard](https://img.shields.io/badge/MCP-1.0.0-blue.svg)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Zero-Config Sandbox](https://img.shields.io/badge/Sandbox-50_Canons_Offline-brightgreen.svg)](#zero-config-golden-sandbox)
+[![Dual-Track Pricing](https://img.shields.io/badge/Pricing-Payoneer_%7C_WeChat_%7C_Alipay-orange.svg)](#dual-track-pricing--access-tiers)
+
+---
+
+## 🌟 Why VeriScope? Three A/B Scenarios
+
+When AI Agents conduct research, general-purpose LLMs generate plausible yet ungrounded citations, fabricate page numbers, or flatten vigorous intellectual conflicts into milquetoast compromises. VeriScope provides a **deterministic factual anchor**:
+
+### Scenario 1: Max Weber Citation Verification (*The Protestant Ethic*)
+* **The Task**: "Cite Max Weber's precise German-to-English thesis on the spirit of capitalism and its ascetic calling."
+* ❌ **Vanilla LLM (Hallucinated)**:
+  > "Weber writes in Chapter 2, page 181: 'The modern capitalist spirit arose purely from Calvinist predestination.' (Weber, 1905, Scribner edition)."
+  > *Audit*: Fabricated page number; inaccurate quotation; no cryptographic edition hash.
+* ✅ **VeriScope MCP (`veriscope_locate_evidence`)**:
+  > **Edition**: *The Protestant Ethic and the Spirit of Capitalism* (Archival ID: Sovereign Harbor Verified Edition)  
+  > **Coordinate**: Section 2: "The Spirit of Capitalism", Paragraph 12  
+  > **Verbatim Excerpt (<=300 chars)**: *"Man is dominated by the making of money, by acquisition as the ultimate purpose of his life. Economic acquisition is no longer subordinated to man as the means for the satisfaction of his material needs."*  
+  > **Edition SHA-256**: `d7a8fbb5628549...3984e1`  
+  > **Receipt**: `vsk_sig:ed25519_8f0a2e...` (Cryptographically verified against tamper-lock)
+
+---
+
+### Scenario 2: Hans Kelsen vs. Carl Schmitt on Legal Sovereignty
+* **The Task**: "Contrast Hans Kelsen's Pure Theory of Law with Carl Schmitt's Decisionism regarding the State of Exception."
+* ❌ **Vanilla LLM (Flat Synthesis)**:
+  > "Both scholars contributed to German legal theory. Kelsen believed in the rule of law and the Basic Norm, while Schmitt emphasized political authority during crises. They represent complementary aspects of jurisprudence."
+  > *Audit*: Flattens an irreconcilable Weimar constitutional duel into false harmony.
+* ✅ **VeriScope MCP (`veriscope_inspect_topography`)**:
+  > **Formal Kernel**: Pure normativism (*Reine Rechtslehre*) vs. Political existential decisionism (*Dezisionismus*).  
+  > **Lineages**: Hans Kelsen (Wikidata Q84322) vs. Carl Schmitt (Wikidata Q57476).  
+  > **Dialectical Disputes (3 Core Theses)**:
+  > 1. *Norm vs. Exception*: Kelsen posits law as a self-contained hierarchy deriving validity solely from the Grundnorm; Schmitt counters that the sovereign is "he who decides on the exception" (*Ausnahmezustand*), where norm yields to concrete order.
+  > 2. *Guardian of the Constitution*: Kelsen's 1928 constitutional court doctrine vs. Schmitt's 1931 *Der Huter der Verfassung* asserting the Reich President as sole guardian.
+  > 3. *Validity vs. Facticity*: Logical purity of legal norms versus existential political will.
+
+---
+
+### Scenario 3: Keynesian Liquidity Trap (*General Theory*)
+* **The Task**: "Explain the exact institutional boundary of Keynes's liquidity trap and verify against primary economic texts."
+* ❌ **Vanilla LLM (Secondary Paraphrase)**:
+  > "Keynes explained that when interest rates are zero, monetary policy becomes ineffective because people hold cash."
+* ✅ **VeriScope MCP (`veriscope_locate_evidence` & `veriscope_verify_attestation`)**:
+  > **Formal Axiom**: Absolute liquidity preference under asymptotic flat LM-curve conditions where $\partial M / \partial r 	o \infty$.  
+  > **Primary Location**: *The General Theory of Employment, Interest and Money*, Chapter 15 ("The Psychological and Business Incentives to Liquidity"), Section II.  
+  > **Verification Status**: `VERIFIED_AUTHENTIC` (SHA-256 matched with primary English edition).
+
+---
+
+## 🛠️ The 4+1 Cognitive Funnel Tool Matrix
+
+| Tool Name | Input Parameters | Primary Output | Use Case |
+| :--- | :--- | :--- | :--- |
+| `veriscope_discover_concepts` | `query: str`, `discipline_hint?: str` | Standardized canonical ontology, formal definition, Sino-Western comparative counterpart | Elevate colloquial concepts or news metaphors into formal academic disciplines |
+| `veriscope_inspect_topography` | `concept_id: str` | `formal_kernel`, Wikidata QIDs, and 3+ structured `dialectical_disputes` | Prevent shallow syntheses; ground the agent in historical debates and rival axioms |
+| `veriscope_locate_evidence` | `concept_id: str`, `proposition?: str` | Verbatim fair-use slice (**<=300 chars**), chapter coordinate, 64-bit SHA-256, Ed25519 receipt | Ground claims in physical verified editions with peer-reviewable cryptographic proof |
+| `veriscope_verify_attestation` | `concept_id: str`, `claimed_sha256: str`, `verbatim_slice?: str` | `is_valid: bool`, `verification_status: "VERIFIED_AUTHENTIC" \| "TAMPER_DETECTED"` | Zero-knowledge cryptographic check for citations, journal peer review, and fact auditing |
+| `veriscope_probe_radar` | `concept_id: str` | Cross-disciplinary synaptic radar links, epistemological blind spots | Interdisciplinary research, cognitive blind spot alerts, and synthetic conceptual discovery |
+
+---
+
+## ⚡ Zero-Config Golden Sandbox
+
+VeriScope ships with a **built-in 50-Canon Golden Sandbox** (`golden_sandbox_50.json`, ~126 KB). 
+
+* **Instant Offline Exploration**: Reviewers and developers can inspect, locate, and verify citations immediately upon installation **without signing up or providing any API key**.
+* **10 Disciplines x 5 Canons**: Covers Philosophy (Kant, Plato, Descartes, Nietzsche, Spinoza), Sociology (Weber, Durkheim, Marx, Simmel, Parsons), Political Theory (Schmitt, Hobbes, Locke, Machiavelli, Rawls), Economics (Keynes, Smith, Hayek, Schumpeter, Ricardo), Law (Kelsen, Hart, Dworkin, Fuller, Savigny), History, Literature, Psychology, Communication, and Philosophy of Science (Kuhn, Popper, Lakatos, Feyerabend, Merton).
+* **Teaser Mode for Long-Tail Canons**: When querying concepts beyond the 50 sandbox canons without an API key, VeriScope **does not crash with a 401 error**. Instead, it returns a **Cryptographic Teaser Preview** containing the matched canon title, chapter coordinate, and a non-empty `canon_sha256_prefix`, keeping the Agent's reasoning workflow alive.
+
+---
+
+## 💳 Dual-Track Pricing & Access Tiers
+
+VeriScope utilizes a **hybrid subscription and credit-pack model** designed to eliminate per-call micro-payment anxiety for automated research pipelines:
+
+| Plan / Tier | Target Audience | Domestic Pricing (WeChat / Alipay) | Global Pricing (Payoneer Checkout) | Included Quota / Benefits |
+| :--- | :--- | :--- | :--- | :--- |
+| **Community Sandbox** | Developers & Evaluators | **Free (¥0)** | **Free ($0)** | 50 Golden Canons full access + Teaser previews for all long-tail concepts |
+| **Scholar Pro** | Researchers & PhD Candidates | **¥128 / month** | **$19 / month** | Unlimited standard queries, 5,000 evidence slices/mo, full Ed25519 attestation receipts |
+| **Power Credit Pack** | Agent Builders & Automated Pipelines | **¥68 / 500 credits** | **$10 / 500 credits** | Flexible top-up for high-frequency automated batch synthesis |
+| **Enterprise / Institution** | Academic Labs & Law Firms | **¥5,000 / year** | **$800 / year** | Dedicated rate limits, IP whitelist, institutional co-signing keys, SLA guarantee |
+
+*To activate your key, visit [https://veriscope.cc/pricing](https://veriscope.cc/pricing) or configure `VERISCOPE_API_KEY`.*
+
+---
+
+## 🚀 Quick Start & Integration
+
+### Claude Desktop / Claude Code
+Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "veriscope": {
+      "command": "npx",
+      "args": ["-y", "@veriscope/mcp-server"],
+      "env": {
+        "VERISCOPE_API_KEY": "vsk_live_optional_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor & Windsurf
+Add as a new stdio MCP server:
+- **Command**: `npx`
+- **Arguments**: `-y @veriscope/mcp-server`
+
+### Python / uvx Alternative
+```json
+{
+  "mcpServers": {
+    "veriscope": {
+      "command": "uvx",
+      "args": ["veriscope-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 🔒 Security, Privacy & Scholarly Fair-Use Compliance
+
+1. **Read-Only Engine**: VeriScope operates strictly in read-only mode (`mode=ro`). It never writes to the host filesystem.
+2. **Scholarly Fair-Use Doctrine**: VeriScope is a cryptographic bibliographic index and citation verification engine. It never distributes or transmits full book copies; verbatim evidence excerpts are hard-capped at **strictly <=300 characters** around the proposition anchor.
+3. **Cryptographic Ed25519 Receipts**: Every attested quote is signed with the slice's 16-hex hash (`slice_sha256_16`) in the payload `VERISCOPE_ATTESTATION:{concept_id}:{canon_sha256}:{slice_sha16}:{timestamp}`, providing tamper-evident authenticity for scholarly peer review.
+4. **Entropy Rate Limiting (F8 Shield)**: High-entropy scraping attacks triggering cross-disciplinary jumps across $\ge 6$ disciplines in short bursts automatically drop into **Zero-Text Proof Mode** (yielding only coordinates and SHA-256 prefixes), protecting the sovereign archive while maintaining zero-hallucination factual integrity.
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/README_ZH.md

@@ -0,0 +1,155 @@
+# 真镜 v3.0 MCP Server
+
+> **真镜** = 知识证据溯源系统。素书楼馆藏实体原本与全量学术文献 (FTS5+INSTR 段落级定位) · 7.5万张卡片 (22学科) · 2.1万条双链 · 27个学术社区 · 476万共现对。核心动作：输入命题 → 输出可信等级 + 支持/反对证据 + 谱系 + 盲区 + 原文锚点。
+
+---
+
+## 这是什么？
+
+**MCP Server** 是真镜的 **Model Context Protocol (MCP)** 服务端实现，把真镜的 5 个核心 Skill（三态取证 / 概念地形图 / 书目深挖 / 验证 / 学者谱系）暴露为标准化的 MCP Tools。
+
+**为什么需要？**
+- 40+ AI Agent（Claude Code / Cursor / Codex / Gemini / 等）可通过 MCP 协议**直接调用真镜能力**，无需浏览器插件
+- 这是真镜 v3.0 **L4 生态与入口层**的关键一环（见架构文档 §二·四层架构模型 L4）
+- **不是 Chrome 插件的替代**——插件入口思维不变（§七-4 不变量），MCP Server 是**额外的入口**，服务于 AI Agent 生态
+
+---
+
+## 核心能力（5 个 MCP Tools）
+
+| Tool 名称 | 对应 Skill | 端点 | 说明 |
+|-----------|------------|------|------|
+| `three-state-evidence` | 三态取证 | `/api/collision/duel` | 相关/对立/缺口 三态证据验证 |
+| `concept-terrain` | 概念地形图 | `/api/concept/terrain` | 概念的层位、谱系、盲区全景 |
+| `book-deep-dive` | 书目深挖 | `/api/topology/evidence-concept` | 单本书的论点、谱系、关联卡片、盲区 |
+| `verify` | 验证模式 | `/api/collision/en` | 英文入口：声明溯源 + 对立证据 |
+| `scholar-lineage` | 学者谱系 | `/api/thinker/biography` | 学者的影响、代表作、关联思想家 |
+
+---
+
+## 安装
+
+```bash
+cd F:\翰林院AI总账本
+pip install mcp  # 可选，mock 模式不需要
+```
+
+> **零额外依赖**：核心逻辑仅用标准库。`mcp` 包仅在真实 MCP 连接时需要；mock 模式（`--list-tools`）零依赖。
+
+---
+
+## 启动方式
+
+### 1. MCP stdio 模式（供 AI Agent 连接）
+```bash
+python -m mcp_server.veriscope_mcp_server
+```
+
+### 2. Mock 模式（无 MCP SDK 时验证）
+```bash
+python -m mcp_server.veriscope_mcp_server --list-tools
+python -m mcp_server.veriscope_mcp_server --call-tool three-state-evidence --args '{"lens_card_id":"abc","opponent_card_id":"def"}'
+```
+
+---
+
+## 与 AI Agent 集成示例
+
+### Claude Code / Cursor / Codex / Gemini
+```json
+{
+  "mcpServers": {
+    "veriscope": {
+      "command": "python",
+      "args": ["-m", "mcp_server.veriscope_mcp_server"],
+      "cwd": "F:/翰林院AI总账本"
+    }
+  }
+}
+```
+
+---
+
+## 架构定位：与 v3.0 §七-4 不变量的关系
+
+> **不变量 4：插件入口思维不变** —— 所有外部入口（MCP / Skill Registry）最终汇聚到 Chrome 插件这一人类入口
+
+```
+L4: Chrome插件(人类) / MCP Server(AI Agent) / Skill Registry / K-Dense互导流
+  ↓ 统一路由（建议1）
+L2: archive_server.py 统一路由技能
+  ↓
+L3: 三态取证 / Evidence Object 9字段 / 行级锚定
+  ↓
+L1: 素书楼学术原典实物物证库 + FTS5 + INSTR + SHA256
+```
+
+**关键点**：
+- MCP Server **不绕过** archive_server.py，通过 `skills_adapter.py` **直接 import 调用** view function
+- 所有证据产出遵循 **Evidence Object 9 字段 schema**（`evidence_object_schema.json`）
+- 三态取证（相关/对立/缺口）哲学核心 **不变**（§七-3）
+
+---
+
+## 与 K-Dense plugin.json 的关系
+
+参考 `decisions/_refs/k_dense_scientific_agent_skills_v2.64.0/plugin.json`（23 行标准模板）。真镜 MCP Server 遵循同一 **Agent Plugins 1.0.0 标准**：
+- `name`/`version`/`description`/`author`/`license`/`keywords` 字段对齐
+- Skill 目录结构遵循 K-Dense 硬规范：`SKILL.md` + `references/` + `scripts/` + `assets/`
+- `metadata.version` 必须引号包字符串（如 `"0.1"`）
+- `allowed-tools` 为空格分隔字符串
+
+---
+
+## 内部实现要点
+
+| 文件 | 职责 | 行数 |
+|------|------|------|
+| `veriscope_mcp_server.py` | MCP Server 核心，优雅降级，stdio transport | ~160 |
+| `skills_adapter.py` | registry.json → MCP Tool 定义 + 本地调用 archive_server | ~180 |
+| `__init__.py` | 包元信息 | ~15 |
+
+**关键设计**：
+1. **不强依赖 mcp SDK**：`try/except ImportError` 优雅降级，mock 模式可独立运行
+2. **本地调用而非 HTTP**：Flask `test_request_context` 直接调用 view function，零网络开销
+3. **param_mapping 自动生成 schema**：registry.json → JSON Schema（inputSchema）
+4. **stdio transport**：标准 MCP 协议，兼容所有 MCP Client
+
+---
+
+## 验证
+
+```bash
+python -c "import ast; ast.parse(open('mcp_server/veriscope_mcp_server.py', encoding='utf-8').read())"
+python -c "import ast; ast.parse(open('mcp_server/skills_adapter.py', encoding='utf-8').read())"
+python -m mcp_server.veriscope_mcp_server --list-tools  # 应显示 5 个 tool
+python -m mcp_server.skills_adapter
+```
+
+---
+
+## 回归风险控制
+
+| 风险 | 对策 |
+|------|------|
+| 改动现有文件 | **严禁**改动 `archive_server.py` / `prompts.toml` / `sidebar.*` 等 |
+| 强依赖 mcp SDK | `try/except` 优雅降级，mock 模式完整可用 |
+| 引入额外依赖 | 仅标准库 + `mcp`（可选） |
+| 暴露 secrets | 无 API key / secret 硬编码 |
+| 破坏插件入口 | MCP Server 只是**额外入口**，插件主入口不受影响 |
+
+---
+
+## 后续规划（P2 阶段）
+
+- [ ] 真实 MCP SDK 集成测试
+- [ ] Evidence Object 9 字段在 tool 返回中透传
+- [ ] 支持 `/skill/<name>` 统一路由技能（建议 1）
+- [ ] K-Dense 互导流：双向路由 + 数据交换
+- [ ] 安全扫描集成（Cisco AI Defense Skill Scanner）
+
+---
+
+## 许可证
+
+MIT License — 与真镜主项目一致。