blawx MCP

blawx mcp

使用Blawx API密钥调用Blawx API的最低运行量MCP服务器。

前提条件

• Python 3.10+

安装

从这个repo根目录：

python -m pip install -e .

示例：Windows+Claude桌面

这是在Windows上为Claude Desktop本地设置MCP服务器的一种方法。

1. 在本地克隆存储库。

git clone https://github.com/Lexpedite/blawx_mcp.git
cd blawx_mcp

1. 安装软件包。

python -m pip install .

1. 从Blawx配置文件页面生成API密钥。在左侧导航栏中，单击“配置文件”，然后使用“添加API密钥”按钮。显示密钥时复制密钥。

1. 将MCP服务器添加到Claude Desktop配置文件中，通常在 %APPDATA%\Claude\claude_desktop_config.json:

{
	"mcpServers": {
		"blawx-mcp": {
			"command": "python",
			"args": ["-m", "blawx_mcp", "--stdio"],
			"env": {
				"BLAWX_API_KEY": "your API Key Here"
			}
		}
	}
}

MCP服务器不再需要 team_slug 或 project_id 在启动时。代理在运行时通过以下方式发现团队 blawx_teams_list，选择一个团队成员，然后使用以下工具发现项目 blawx_projects_list.

您需要完全退出Claude Desktop（使用系统托盘中的Claude图标并选择“退出”，然后重新启动），并重新启动 配置更改生效。

配置

在您的环境中设置所需的配置：

export BLAWX_API_KEY="your_key_here"

团队和项目选择发生在工具调用时间，而不是启动时间。 使用 blawx_teams_list 连接服务器后。如果它只返回一个团队，则使用该团队的 slug 作为 team_slug；如果它返回多个团队，而用户尚未确定一个团队，请询问用户要使用哪个团队。然后打电话 blawx_projects_list 和 team_slug 并通过两者 team_slug 和返回 project_id 每个项目范围的工具。

如果您有Blawx的Pro订阅，则可以创建Blawx API密钥。 点击左侧导航栏中的“配置文件”，找到“添加API 键”按钮。当您单击该按钮时，将显示您的API键 仅在屏幕顶部显示一次。复制并粘贴到您的 环境设置。

跑

从此文件夹运行MCP服务器（无需安装）。

对于SSE/HTTP传输：

./.venv/bin/python -m blawx_mcp

默认值：

• 绑定到 127.0.0.1:8765
• SSE端点位于 http://127.0.0.1:8765/sse

可选的服务器绑定覆盖：

export BLAWX_MCP_HOST="127.0.0.1"
export BLAWX_MCP_PORT="8765"

对于stdio传输，这对本地客户端（如Claude Desktop）很有用：

./.venv/bin/python -m blawx_mcp --stdio

连接到您的编码代理

编码代理在配置MCP服务器的方式上有所不同。这是一个典型的 工具定义 mcp.json 对于VS代码。

{
	"servers": {
		"my-blawx-sse-server": {
			"url": "http://127.0.0.1:8765/sse",
			"type": "http"
		}
	},
	"inputs": []
}

工具

这些工具为您的编码代理提供了以下功能：

所有项目范围的工具都需要两者 team_slug 和 project_id代理人应随时致电 blawx_teams_list 第一。如果只有一个团队，则使用该团队的slug；如果有多个团队，而用户还没有确定一个，请询问用户要使用哪个团队。然后打电话 blawx_projects_list 说完这个 team_slug 并通过两者 team_slug 和返回 project_id 到后来的每一个本体、法律文档、问题、事实场景、问答和编码工具。

1. 发现团队并选择 team_slug.
2. 发现该团队下的项目并选择 project_id.
3. 发现所选项目暴露的内容（问题、事实场景、本体论）。
4. 创建、更新和删除LegalDocs、LegalDocParts和EncodingParts。
5. 提出一个问题（使用存储事实场景或自定义事实有效负载）。
6. 浏览答案并深入解释（模型/属性/解释文本）。

以下是可用工具的简要概述。

健康检查

• blawx_health：验证Blawx应用程序是否可访问，并返回状态/body。

发现项目内容

代理应首先列出团队，然后列出所选团队下的项目。

• blawx_teams_list：列出可用于配置的API密钥的团队。
• blawx_projects_list：列出了可用的项目 team_slug.
• blawx_project_detail：检索特定项目id的元数据。

一旦选择了团队和项目，每个项目范围的工具都需要明确的 team_slug 和 project_id 论据。 然后，代理人通常会列出可用的问题、事实场景和词汇。

• blawx_questions_list：列出了项目中可用的共享问题。
• blawx_question_detail：检索特定问题的详细信息（在决定要问哪个问题时很有用）。
• blawx_fact_scenarios_list：列出存储的事实场景（可以重复使用的预构建事实集）。
• blawx_fact_scenario_detail：显示特定事实场景中包含的事实。
• blawx_ontology_list：列出本体类别/关系（项目的词汇表）。
• blawx_ontology_category_detail：特定类别的详细信息。
• blawx_ontology_relationship_detail：特定关系的详细信息（包括arity/参数）。

其他读写工具也可用于项目编辑（问题、事实场景、本体类别/关系/参数）。

示例：

{
	"team_slug": "my-team",
	"project_id": 60
}

{
	"team_slug": "my-team",
	"project_id": 60,
	"question_id": 123
}

对于写入操作：

• blawx_encodingpart_update, blawx_question_create, blawx_question_update, blawx_fact_scenario_create，以及 blawx_fact_scenario_update 所有这些都使用相同的有效载荷形状：

{
	"payload": {
		"blawx_json": {
			"...": "..."
		}
	}
}

具体来说，对于问题保存，编码应包含一个外部问题块。

• 本体编写工具接受普通JSON对象 payload，不 blawx_json 工作空间。

当前API验证需要以下最小形状：

{
	"payload": {
		"name": "Contract",
		"slug": "contract",
		"short_description": "",
		"nlg_prefix": "",
		"nlg_postfix": "is a contract"
	}
}

{
	"payload": {
		"name": "Estimated Expenditure",
		"slug": "estimated_expenditure",
		"short_description": "",
		"nlg_prefix": ""
	}
}

{
	"relationship_id": 458,
	"payload": {
		"order": 1,
		"type_id": 466,
		"nlg_postfix": ""
	}
}

笔记：

• 类别创建/更新当前需要 name 和 slug; nlg_postfix 必须不超过50个字符。
• 关系创建/更新当前需要 name 和 slug.
• 关系参数创建/更新当前需要 order 和 type_id.
• 使用 blawx_ontology_categories_list 或 blawx_ontology_category_detail 为发现有效的类别id type_id.

此MCP服务器中有意不公开补丁样式的工具，以减少工具选择的歧义。

提出问题

• blawx_question_ask_with_fact_scenario：使用存储事实场景提问。
• blawx_question_ask_with_facts：使用您的代理根据您的

说明。

两种提问工具都需要 team_slug 和 project_id 除了 question_id 以及它们各自的有效载荷参数。

目前，这两种提问工具都需要共享问题。 如果你打电话 blawx_question_ask_with_fact_scenario 或 blawx_question_ask_with_facts 使用非共享问题id，Blawx应用程序可能会返回 Question not available via API. 使用以下问题 blawx_questions_list, 或设置 shared: true 首先，关于这个问题。

牛逼：目前尚不清楚代理人在生成方面有多好 复杂事实情景的表示 词汇。查看您的代理如何操作可能会有所帮助 如果你得到意想不到的结果，制定你的事实情景， 并给出如何做得更好的提示。

当您提出问题时，答案会保存在Blawx上 服务器大约30分钟，您的代理可以 在这段时间内回顾一下。一旦数据到期， 你的代理人需要再次提出问题进行分析 进一步的回应。根据提供的说明 通过MCP服务器，它应该知道何时以及是否这样做 必修的。

查看答案

Blawx的答案可能相当大，代理的答案也有限 上下文窗口，因此审查过程 答案分为多个步骤。

1. 获取问题的答案列表。
2. 获取特定答案的解释列表。
3. 看看具体解释的各个部分。

• blawx_list_answers：给出可用答案列表，

以及这些答案中的绑定。

• blawx_cached_response_meta：缓存响应的元数据（ttl、created、answer_count）。

• blawx_list_explanations：给出可供回答的解释列表

有四种工具可以检索 解释。这些工具都允许代理选择 整个部分，或者如果太长，只选择某些部分 一次行。

• blawx_get_model_part：这将返回答案集
• blawx_get_attributes_part：这将返回应用于模型中变量的约束和解释
• blawx_get_explanation_part：这是树形结构，

人类可读的答案解释

• blawx_get_constraint_satisfaction_part：这就是那部分

关于如何满足全局约束的解释。这通常既冗长又无益，所以 是分开的。你可能需要让你的代理人去寻找它 特别是如果你知道你的编码使用了约束和 你需要了解他们的满意度。

法律文件+编码

API支持读写法律文档、法律文档部分和编码部分，此MCP服务器现在公开了所有三层的CRUD工具。

• blawx_legaldocs_list, blawx_legaldoc_create, blawx_legaldoc_detail, blawx_legaldoc_update, blawx_legaldoc_delete
• blawx_legaldocparts_list, blawx_legaldocpart_create, blawx_legaldocpart_detail, blawx_legaldocpart_update, blawx_legaldocpart_delete
• blawx_encoding_guide, blawx_encodingpart_get, blawx_encodingpart_update, blawx_encodingpart_delete

所有这些工具都需要 team_slug 和 project_id.

默认LegalDocPart粒度规则：保留立法层次结构。每个标题都有自己的部分，每个节都有自己节级文本的部分，没有下属单位的节是一个部分，当每个小节、段落或类似的下属单位有不同的文本时，它也有自己的一部分。不要仅仅因为逻辑相关就将单独可寻址的立法单位合并为一个部分。

获取完整的LegalDocPart结构指南，包括 parent_id, include_parent, include_sibling，并举例说明，请阅读 blawx_encoding_guide 主题 legaldocs.

要阅读立法文本，请使用以下顺序：

1. blawx_teams_list 选择a team_slug.
2. blawx_projects_list 选择a project_id.
3. blawx_legaldocs_list （或 blawx_legaldoc_detail)识别a legal_doc_id.
4. blawx_legaldocparts_list 列出该文档的零件ID/标题/顺序。
5. blawx_legaldocpart_detail 对于每一个相关 legal_doc_part_id 以检索实际的零件文本/内容。

blawx_legaldocparts_list 主要是导航元数据； blawx_legaldocpart_detail 是返回特定部分文本的工具。

要创建或更新文档结构，请执行以下操作：

1. blawx_encoding_guide 与主题 legaldocs.
2. blawx_legaldoc_create 或 blawx_legaldoc_update 带有效载荷：

{
	"team_slug": "my-team",
	"project_id": 60,
	"payload": {
		"name": "Financial Administration Act",
		"slug": "FAA",
		"tag_ids": []
	}
}

1. blawx_legaldocpart_create 有效载荷例如：

{
	"team_slug": "my-team",
	"project_id": 60,
	"legal_doc_id": 78,
	"payload": {
		"element_type": "Section",
		"index_text": "41",
		"text_content": "No contract shall be entered into...",
		"substantive": true
	}
}

对于零件更新，省略 parent_id.当前的Blawx API拒绝通过PUT重新分配。

请先使用此序列:

1. 呼叫 blawx_encoding_guide （主题 quickstart那么 encoding-process那么 encodingpart那么 blawx-json).

其他可用主题包括： - valid-blawx-json：具体有效的有效载荷模式 blawx_json - blawx-blocks：快速参考可用块类型和所需组件 - encoding-process：创建和更新编码部件的分步工作流程 - legaldocs：LegalDoc和LegalDocPart结构、写入字段和项目选择工作流

1. 呼叫 blawx_encodingpart_get 检查现有编码。
2. 呼叫 blawx_encodingpart_update 有效载荷形状：

{
	"payload": {
		"blawx_json": {
			"...": "..."
		}
	}
}

blawx_encodingpart_update 仅接受 Blawx JSON块 通过 payload.blawx_json。不要发送 content, scasp_encoding，或字符串化JSON。

牛逼：其他三个部分应与 可能缺少属性或相关信息。这 向代理提供指示，但如果不遵守指示 你的代理人可能会得出错误的结论。也许明智的做法是 指示您的代理检查属性以及 解释的其他部分。

典型工作流程

1. 使用启动服务器 BLAWX_API_KEY.
2. 呼叫 blawx_teams_list 并选择一个 team_slug；如果只有一个团队返回，请使用它。
3. 呼叫 blawx_projects_list 和 team_slug 并选择一个 project_id.
4. 传递这个 team_slug 和 project_id 本体论、事实场景、问题、问答、法律文档、法律文档部分和编码部分工具。

发展

可以覆盖所使用的Blawx服务器以进行本地开发

• BLAWX_BASE_URL （默认值： https://app.blawx.dev)

嵌入为库（多租户/托管使用）

blawx_mcp 可以作为库导入到托管的多租户服务器中。使用 settings_context() 按请求注射 Settings 因此，来自的并发请求 不同的用户在配置或缓存状态上永远不会发生冲突。

from blawx_mcp import Settings, settings_context
from blawx_mcp.config import _settings_override

settings = Settings(
    base_url="https://app.blawx.dev",
    api_key="my-key",
)
token = settings_context(settings)
try:
    # ... invoke MCP tools in this async context ...
    pass
finally:
    _settings_override.reset(token)

settings_context() 使用Python contextvars.ContextVar 引擎盖下 异步安全：每个 asyncio 任务继承了它自己的上下文副本，因此是并发的 即使在同一事件循环中运行，请求也不会发生冲突。团队选择是 由MCP工具参数提供，因此托管消费者应该通过 team_slug 通过 团队范围的工具调用，而不是将其注入到设置中。