decompose-mcp

将任何文本分解为分类语义单元——权威、风险、注意力、实体。没有法学硕士。确定性的。

# Decompose

Decompose any text or URL into classified semantic units. Each unit gets authority level, risk category, attention score, entity extraction, and irreducibility flags. No LLM required. Deterministic. Runs locally.

## Setup

### 1. Install

```bash
pip install decompose-mcp
```

### 2. Configure MCP Server

Add to your OpenClaw MCP config:

```json
{
  "mcpServers": {
    "decompose": {
      "command": "python3",
      "args": ["-m", "decompose", "--serve"]
    }
  }
}
```

### 3. Verify

```bash
python3 -m decompose --text "The contractor shall provide all materials per ASTM C150-20."
```

## Available Tools

### `decompose_text`

Decompose any text into classified semantic units.

**Parameters:**
- `text` (required) — The text to decompose
- `compact` (optional, default: false) — Omit zero-value fields for smaller output
- `chunk_size` (optional, default: 2000) — Max characters per unit

**Example prompt:** "Decompose this spec and tell me which sections are mandatory"

**Returns:** JSON with `units` array. Each unit contains:
- `authority` — mandatory, prohibitive, directive, permissive, conditional, informational
- `risk` — safety_critical, security, compliance, financial, contractual, advisory, informational
- `attention` — 0.0 to 10.0 priority score
- `actionable` — whether someone needs to act on this
- `irreducible` — whether content must be preserved verbatim
- `entities` — referenced standards and codes (ASTM, ASCE, IBC, OSHA, etc.)
- `dates` — extracted date references
- `financial` — extracted dollar amounts and percentages
- `heading_path` — document structure hierarchy

### `decompose_url`

Fetch a URL and decompose its content. Handles HTML, Markdown, and plain text.

**Parameters:**
- `url` (required) — URL to fetch and decompose
- `compact` (optional, default: false) — Omit zero-value fields

**Example prompt:** "Decompose https://spec.example.com/transport and show me the security requirements"

## What It Detects

- **Authority levels** — RFC 2119 keywords: "shall" = mandatory, "should" = directive, "may" = permissive
- **Risk categories** — safety-critical, security, compliance, financial, contractual
- **Attention scoring** — authority weight x risk multiplier, 0-10 scale
- **Standards references** — ASTM, ASCE, IBC, OSHA, ACI, AISC, AWS, ISO, EN
- **Financial values** — dollar amounts, percentages, retainage, liquidated damages
- **Dates** — deadlines, milestones, notice periods
- **Irreducibility** — legal mandates, threshold values, formulas that cannot be paraphrased

## Use Cases

- Pre-process documents before sending to your LLM — save 60-80% of context window
- Classify specs, contracts, policies, regulations by obligation level
- Extract standards references and compliance requirements
- Route high-attention content to specialized analysis chains
- Build structured training data from raw documents

## Performance

- ~14ms average per document on Apple Silicon
- 1,000+ chars/ms throughput
- Zero API calls, zero cost, works offline
- Deterministic — same input always produces same output

## Security & Trust

**Text classification is fully local.** The `decompose_text` tool performs all processing in-process with no network I/O. No data leaves your machine.

**URL fetching performs outbound HTTP requests.** The `decompose_url` tool fetches the target URL, which necessarily involves network I/O to the specified host. This is why the skill declares the `network` permission in `claw.json`. If you do not need URL fetching, you can use `decompose_text` exclusively with no network access required.

**SSRF protection.** URL fetching blocks private/internal IP ranges before connecting: `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `::1/128`, `fc00::/7`, `fe80::/10`. The implementation resolves the hostname via DNS *before* connecting and checks all returned addresses against the blocklist. See [`src/decompose/mcp_server.py` lines 19-49](https://github.com/echology-io/decompose/blob/main/src/decompose/mcp_server.py#L19-L49).

**No API keys or credentials required.** No external services are contacted except when using `decompose_url` to fetch user-specified URLs.

**Source code is fully auditable.** The complete source is published at [github.com/echology-io/decompose](https://github.com/echology-io/decompose). The PyPI package is built from this repo via GitHub Actions ([`publish.yml`](https://github.com/echology-io/decompose/blob/main/.github/workflows/publish.yml)) using PyPI Trusted Publishers (OIDC), so the published artifact is traceable to a specific commit.

## Resources

- [Source Code (GitHub)](https://github.com/echology-io/decompose) — full source, auditable
- [PyPI](https://pypi.org/project/decompose-mcp/) — published via Trusted Publishers
- [Documentation](https://echology.io/decompose)
- [Blog: When Regex Beats an LLM](https://echology.io/blog/regex-beats-llm)
- [Blog: Why Your Agent Needs a Cognitive Primitive](https://echology.io/blog/cognitive-primitive)

---

## 中文说明

# Decompose

将任意文本或 URL 分解为已分类的语义单元。每个单元都会获得权威级别、风险类别、注意力评分、实体提取以及不可约简标记。无需 LLM。确定性。本地运行。

## 设置

### 1. 安装

```bash
pip install decompose-mcp
```

### 2. 配置 MCP 服务器

添加到你的 OpenClaw MCP 配置中：

```json
{
  "mcpServers": {
    "decompose": {
      "command": "python3",
      "args": ["-m", "decompose", "--serve"]
    }
  }
}
```

### 3. 验证

```bash
python3 -m decompose --text "The contractor shall provide all materials per ASTM C150-20."
```

## 可用工具

### `decompose_text`

将任意文本分解为已分类的语义单元。

**参数：**
- `text`（必填）—— 要分解的文本
- `compact`（可选，默认：false）—— 省略零值字段以减小输出体积
- `chunk_size`（可选，默认：2000）—— 每个单元的最大字符数

**示例提示词：** "Decompose this spec and tell me which sections are mandatory"

**返回：** 包含 `units` 数组的 JSON。每个单元包含：
- `authority` —— mandatory、prohibitive、directive、permissive、conditional、informational
- `risk` —— safety_critical、security、compliance、financial、contractual、advisory、informational
- `attention` —— 0.0 到 10.0 的优先级评分
- `actionable` —— 是否需要有人就此采取行动
- `irreducible` —— 内容是否必须逐字保留
- `entities` —— 引用的标准与规范（ASTM、ASCE、IBC、OSHA 等）
- `dates` —— 提取的日期引用
- `financial` —— 提取的金额与百分比
- `heading_path` —— 文档结构层级

### `decompose_url`

抓取一个 URL 并分解其内容。可处理 HTML、Markdown 和纯文本。

**参数：**
- `url`（必填）—— 要抓取并分解的 URL
- `compact`（可选，默认：false）—— 省略零值字段

**示例提示词：** "Decompose https://spec.example.com/transport and show me the security requirements"

## 它能检测什么

- **权威级别** —— RFC 2119 关键词："shall" = mandatory，"should" = directive，"may" = permissive
- **风险类别** —— 安全关键、安全性、合规、财务、合同
- **注意力评分** —— 权威权重 x 风险乘数，0-10 量表
- **标准引用** —— ASTM、ASCE、IBC、OSHA、ACI、AISC、AWS、ISO、EN
- **财务数值** —— 金额、百分比、保留金、违约金
- **日期** —— 截止日期、里程碑、通知期限
- **不可约简性** —— 无法改写的法律强制规定、阈值、公式

## 使用场景

- 在发送给 LLM 之前预处理文档 —— 节省 60-80% 的上下文窗口
- 按义务级别对规范、合同、政策、法规进行分类
- 提取标准引用与合规要求
- 将高注意力内容路由至专门的分析链
- 从原始文档构建结构化训练数据

## 性能

- 在 Apple Silicon 上平均每个文档约 14ms
- 吞吐量 1,000+ 字符/毫秒
- 零 API 调用、零成本、可离线工作
- 确定性 —— 相同输入始终产生相同输出

## 安全与信任

**文本分类完全在本地进行。** `decompose_text` 工具在进程内完成所有处理，无网络 I/O。没有任何数据离开你的机器。

**URL 抓取会发起对外 HTTP 请求。** `decompose_url` 工具会抓取目标 URL，这必然涉及对指定主机的网络 I/O。这正是该技能在 `claw.json` 中声明 `network` 权限的原因。如果你不需要 URL 抓取，可以仅使用 `decompose_text`，无需任何网络访问。

**SSRF 防护。** URL 抓取在连接前会屏蔽私有/内部 IP 段：`0.0.0.0/8`、`10.0.0.0/8`、`100.64.0.0/10`、`127.0.0.0/8`、`169.254.0.0/16`、`172.16.0.0/12`、`192.168.0.0/16`、`::1/128`、`fc00::/7`、`fe80::/10`。其实现会*在连接前*通过 DNS 解析主机名，并将所有返回的地址与屏蔽列表进行核对。参见 [`src/decompose/mcp_server.py` lines 19-49](https://github.com/echology-io/decompose/blob/main/src/decompose/mcp_server.py#L19-L49)。

**无需任何 API 密钥或凭据。** 除使用 `decompose_url` 抓取用户指定的 URL 外，不会联系任何外部服务。

**源代码完全可审计。** 完整源代码发布于 [github.com/echology-io/decompose](https://github.com/echology-io/decompose)。PyPI 包通过 GitHub Actions（[`publish.yml`](https://github.com/echology-io/decompose/blob/main/.github/workflows/publish.yml)）由该仓库构建，并使用 PyPI Trusted Publishers（OIDC），因此发布的产物可追溯到特定的提交。

## 资源

- [Source Code (GitHub)](https://github.com/echology-io/decompose) —— 完整源码，可审计
- [PyPI](https://p