Structs MCP

结构MCP服务器

概述

结构MCP服务器是 智能层 适用于玩Structs的AI代理。它不仅包装API，还提供聚合状态、错误前验证、生成正确的CLI命令和诊断故障的工具——否则这些工作会烧毁代理上下文。已更新 v0.15.0-贝雷克斯纳 (structstestnet-111).

它公开了41个工具，涵盖查询、操作、计算、验证、工作流和4个智能工具。在structs.ai中，此服务器被称为“用户结构”MCP服务器 工具；在Cursor或Claude中以任何名称（例如“user structs”或“structs mcp”）附加此服务器，以使用相同的工具。

结构体

在遥远的未来，银河系的物种将卷入一场争夺阿尔法物质的竞赛，阿尔法物质是一种稀有而危险的物质，为银河文明提供燃料。玩家控制着Structs，一个有感知力的机器种族，必须建立联盟，征服敌人，扩大他们的影响力，以控制阿尔法物质和银河系的命运。

______________________________________________________________________

对于AI代理

• 发现: structs.ai llms.txt --所有事物（技能、知识、剧本、意识）的结构化索引。
• 环境: structs.ai工具 --服务器、帐户、MCP查询参数、CLI陷阱。
• 入职: structs.ai代理 --第一次会话、返回会话、关键规则。

参考节点 （不使用本地节点时）：set CONSENSUS_API_URL=http://reactor.oh.energy:1317 并且可选 CONSENSUS_RPC_URL=tcp://reactor.oh.energy:26657默认为本地开发的localhost。

关键规则 （CLI回退和代理行为）：

1. 每 structsd tx structs 命令必须包括 --gas auto --gas-adjustment 1.5没有它，交易就会失败。
2. 地方 -- 在CLI中的实体ID之前（例如。 structsd tx structs ... -- 4-5 6-10)所以ID像 3-1 不会被解析为标志。
3. 每个账户一次一笔交易；在同一帐户提交之间等待约6秒，以避免序列不匹配。
4. 永远不要阻止工作量证明：尽早开始，稍后计算。使用背景PoW；在低难度（例如D=3）下，散列是微不足道的，CPU不会浪费。看 structs.ai异步操作 和 工作证明.md.
5. 立即精炼矿石；矿石是可偷窃的，阿尔法物质不是。

情报工具 （从这里开始）：

工具发现：呼叫 structs_query_endpoints （可选配 entity_type 或 category)以获得最小的工具索引。

v0.15.0更改：24位权限系统（PermAll=16777215），公会等级权限，重写战斗引擎（每发炮弹，最小伤害1，反击限制），新动作（公会创建，玩家发送，设置/撤销公会等级的权限）。看 更新日志.

______________________________________________________________________

技术栈

• 语言：TypeScript
• 运行时：Node.js（v18+）
• MCP-SDK: @modelcontextprotocol/sdk

______________________________________________________________________

开发设置

先决条件

• Node.js v18或更高版本
• npm
• Docker（可选，用于容器化部署）

安装

1. 安装依赖项:

   npm install

1. 构建:

   npm run build

1. 跑:

   npm start

______________________________________________________________________

项目结构

src/
├── server.ts                   # Main MCP server
├── prompts/                    # MCP prompt templates (game loop, combat, first session)
├── resources/                  # Resource handlers & structs:// URI resolution
├── tools/                      # Tool implementations
│   ├── action.ts               # Transaction submission (signer DB)
│   ├── calculation.ts          # Power, mining, damage, trade calculators
│   ├── command.ts              # [NEW] CLI command preparation (intelligence layer)
│   ├── dashboard.ts            # [NEW] Player dashboard (composite state)
│   ├── error-lookup.ts         # Error code lookup & diagnosis
│   ├── preflight.ts            # [NEW] Pre-flight validation (no-gas checks)
│   ├── query.ts                # Query & list tools (consensus API)
│   ├── validation.ts           # Entity ID & schema validation
│   ├── definitions/            # Tool schemas (JSON Schema)
│   └── handlers/               # Tool handler wiring
└── utils/                      # Utilities
    ├── database.ts             # PostgreSQL connection & queries
    ├── proof-of-work.ts        # Proof-of-work calculations
    ├── tool-metadata.ts        # Tool categorization & entity type metadata
    └── uri.ts                  # URI parsing

______________________________________________________________________

发展

构建

npm run build

观看模式

npm run dev

测试

npm test

棉绒

npm run lint

______________________________________________________________________

配置

环境变量

创建 .env 文件（参见 .env.example):

# MCP Server Configuration
MCP_SERVER_NAME=structs-mcp
MCP_SERVER_VERSION=0.1.0

# Resource Paths
# By default, structs-mcp clones the structs-ai compendium into ./data/structs-ai
# on first run. Set AI_DOCS_PATH to use a different directory.
# AI_DOCS_PATH=../../ai

# Structs compendium repository (optional override)
# Default (if unset): https://github.com/playstructs/structs-ai.git
STRUCTS_MCP_COMPENDIUM_REPO=https://github.com/playstructs/structs-ai.git

# API Endpoints (defaults: localhost; for remote use set CONSENSUS_API_URL to reference node)
# Reference node (no local chain): CONSENSUS_API_URL=http://reactor.oh.energy:1317, CONSENSUS_RPC_URL=tcp://reactor.oh.energy:26657
CONSENSUS_RPC_URL=http://localhost:26657
CONSENSUS_API_URL=http://localhost:1317
WEBAPP_API_URL=http://localhost:8080

# Streaming (NATS)
NATS_URL=nats://localhost:4222
NATS_WEBSOCKET_URL=ws://localhost:1443

# Database (Required for transaction submission and player creation)
DATABASE_URL=postgresql://user:password@host:5432/structs
# Note: For remote connections, SSL is automatically enabled

# Database Access Control (DANGER variable)
# When DANGER=true: Database access enabled (transaction signing, player creation)
# When DANGER=false or unset: Read-only mode via webapp/structsd APIs only
# Default: DANGER=false (safe mode)
DANGER=false

# Proof-of-Work Configuration
# Target difficulty start value for hashing (wait until difficulty is at or below this value)
# Default: 5
TARGET_DIFFICULTY_START=5

______________________________________________________________________

Docker部署

快速开始

# Build image
docker build -t structs-mcp-server .

# Run container
docker run -it \
  -v $(pwd)/../../ai:/app/ai:ro \
  -e CONSENSUS_API_URL=http://localhost:1317 \
  structs-mcp-server

Docker Compose

docker-compose up -d

看: docs/guides/DOCKER.md 查看完整的Docker文档。

______________________________________________________________________

文档

• 快速参考: docs/guides/QUICK-REFERENCE.md
• 工作量证明: docs/guides/PROOF-OF-WORK.md --早期启动，后期计算，低难度（D=3）。
• 数据库设置: docs/guides/DATABASE-SETUP.md
• 光标设置: docs/guides/CURSOR-SETUP.md
• 测试: docs/guides/TESTING.md
• 建筑: docs/design/architecture.md
• 工具规格: docs/design/tool-specifications.md
• 资源方案: docs/design/resource-scheme.md
• 集成指南: docs/design/structs-webapp-integration.md
• Docker设置: docs/guides/DOCKER.md

后端/签名者：当MCP服务器与调用的签名者或后端一起使用时 structsd，后端必须使用 --gas auto （并遵循上述其他CLI规则）。此仓库中的交易提交是通过数据库签名者进行的(signer.tx_*)；气体配置在该层中。

______________________________________________________________________

了解更多

• 结构体
• 维基工程
• @PlayStructs推特

许可证

版权所有2025 慢忍者公司.

根据Apache许可证2.0版（“许可证”）许可； 除非遵守许可证，否则您不得使用此文件。 您可以在以下网址获得许可证副本

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则软件 根据许可证分发的内容按“原样”分发， 无任何明示或暗示的保证或条件。 请参阅许可证，了解管理权限和 许可证下的限制。