OpenSolar MCP

OpenSolar MCP 是一个用于有文档说明的 OpenSolar API 的 Model Context Protocol 服务。它运行在你的设备或基础设施上，使用你自己的 OpenSolar 凭据，为 AI Agent 提供一组精选工具，用于处理项目、联系人、系统、文件、商务设置和 Teams 分享。

flowchart LR
    client["MCP client<br/>Claude · Cursor · VS Code · Codex"]
    server["OpenSolar MCP<br/>runs where you run it"]
    api[("OpenSolar API<br/>api.opensolar.com")]
    client -- "stdio or Streamable HTTP" --> server
    server -- "HTTPS with your bearer token" --> api

重要

本项目与 OpenSolar Pty Ltd 无关联，未获其认可，也不由其维护。本项目仅调用公开且有文档说明的 OpenSolar API，不运营共享或托管的 OpenSolar 服务。

亮点

• 为 Agent 精选。 默认配置包含 31 个日常工作所需的工具。只需更改一项设置，即可使用全部 75 个已注册工具。
• 语义化操作，而不只是端点。 项目和联系人搜索、运营快照、按名称更改阶段、并排比较系统、设计摘要，以及只读分享预检。
• 以谨慎为设计原则。 搜索会报告匹配结果是 unique、ambiguous 还是 incomplete，并告知 Agent 不要猜测。写入操作绝不会自动重试，而只读模式会移除所有修改操作。
• 忠实遵循 OpenSolar 文档。 每个工具都基于官方 API 文档或有记录的实时验证，且仅在请求正文已确认时才开放写入操作。每个工具的依据都列于 API 合约矩阵。
• 保持模型上下文整洁。 提供带公开 schema 的结构化输出。凭据、签名 URL、设计数据块和其他原始或敏感字段会在传递给模型前移除。
• 采用最新 MCP。 基于官方 MCP TypeScript SDK v2 构建，支持 2026-07-28 规范，并为使用较早协议版本的客户端提供回退支持。支持 stdio 和无状态 Streamable HTTP，且每个工具都声明标题、输出 schema 和行为注解。

你可以向 Agent 提出的问题

快速开始

要求

• Node.js 24 或更高版本
• 已启用 API Access 的 OpenSolar 组织
• 你的 OpenSolar 组织 ID 和 bearer token
• 仅当你需要使用 get_proposal_data 或 get_project_design 时，才需要 Raw Data API Access

提示

OpenSolar 标准用户令牌会在七天后过期。对于长期运行的设置，请创建一个专用于 API 操作的 OpenSolar 用户，并将其设为机器用户，其令牌不会过期。此服务绝不会替你更改该设置。

1. 查看你将获得哪些工具（无需凭据）：

npx -y @alignco/opensolar-mcp --list-tools

2. 检查你的配置和令牌：

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --check

--check 会读取一次你的组织信息。添加 --no-probe 可在不联系 OpenSolar 的情况下验证配置。

3. 使用以下选项之一将其添加到你的 MCP 客户端。

连接 MCP 客户端

每个客户端都需要相同的两个设置：OPENSOLAR_API_TOKEN 和 OPENSOLAR_ORG_ID。请将下方的 your_token 和 12345 替换为你自己的值。

claude mcp add opensolar \
  -e OPENSOLAR_API_TOKEN=your_token \
  -e OPENSOLAR_ORG_ID=12345 \
  -- npx -y @alignco/opensolar-mcp

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opensolar_api_token",
      "description": "OpenSolar API token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "opensolar_org_id",
      "description": "OpenSolar organisation ID"
    }
  ],
  "servers": {
    "opensolar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "${input:opensolar_api_token}",
        "OPENSOLAR_ORG_ID": "${input:opensolar_org_id}"
      }
    }
  }
}

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

[mcp_servers.opensolar]
command = "npx"
args = ["-y", "@alignco/opensolar-mcp"]
env = { OPENSOLAR_API_TOKEN = "your_token", OPENSOLAR_ORG_ID = "12345" }

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

npm install -g @alignco/opensolar-mcp
opensolar-mcp --version

提示

熟悉使用方式期间，可先在 env 块中设置 OPENSOLAR_READ_ONLY=1。这会移除所有能够更改 OpenSolar 数据的工具。

工具

配置集

配置集是一组经过整理的操作界面。工具集是可直接选择的功能区域。只读模式和访问计划筛选器均可叠加应用于这两者。

--list-tools 始终会输出你的设置所生成的确切界面：

npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_PROFILE=full npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_TOOLSETS=webhooks npx -y @alignco/opensolar-mcp --list-tools

默认 agent 工具

✏️ 表示会更改 OpenSolar 数据的工具。🔒 表示需要 Raw Data API Access 的工具。

部分已记录的 OpenSolar 操作不会开放，这是因为文档未明确说明其请求正文，例如创建定价方案、付款选项、成本项或组件激活，以及更新工作流或组织。当前实现列出了这些操作。

配置

OPENSOLAR_TOOLSETS 的优先级高于配置。之后会应用 OPENSOLAR_READ_ONLY 和 OPENSOLAR_PLAN。带注释的模板请参阅 .env.example；服务本身不会加载 .env 文件。

本地文件上传

create_private_file 会从运行服务的机器上传文件，因此默认禁用。要启用它，请指定一个目录：

export OPENSOLAR_UPLOAD_ROOT=/absolute/path/to/uploads

相对路径会在该目录内解析。仅当绝对路径和符号链接的实际路径仍位于该目录内时，才会接受它们。模型不会发送文件字节。

通过 get_private_file 和 get_system_image 下载的文件大小上限为 10 MB。文本内容会返回给模型；图像和其他二进制文件会作为 MCP 图像或资源内容返回，而不会复制到 JSON 中。

远程部署

该服务也支持无状态的 Streamable HTTP，供通过网络连接的客户端使用。

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --http

使用 loopback 地址时，Authorization: Bearer <token> 标头优先级更高；OPENSOLAR_API_TOKEN 变量则作为本地备用值。

将其公开到 localhost 以外

任何非回环地址绑定都要求每个 MCP 请求都携带 OpenSolar bearer 令牌。OPENSOLAR_API_TOKEN 变量不会作为备用选项使用，格式错误的 Authorization 标头会被拒绝。

export OPENSOLAR_ORG_ID=12345
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_ALLOWED_HOSTS=mcp.example.com
npx -y @alignco/opensolar-mcp --http

例如，在请求标头中携带令牌来连接客户端：

claude mcp add --transport http opensolar https://mcp.example.com/mcp \
  --header "Authorization: Bearer your_token"

警告

内置服务使用纯 HTTP。在令牌经过任何网络之前，请将其置于可终止 TLS 的反向代理或平台之后。MCP_HTTP_ALLOWED_HOSTS 和 MCP_HTTP_ALLOWED_ORIGINS 用于防范 DNS 重绑定和跨站浏览器请求；它们不提供身份验证。

Docker

该镜像以非特权用户运行 HTTP 传输，并包含健康检查。

docker pull ghcr.io/align-software-company/opensolar-mcp:latest
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/align-software-company/opensolar-mcp:latest

若要从本仓库的克隆版本构建镜像，请改用：

docker build -t opensolar-mcp .
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  opensolar-mcp

在容器内，服务绑定到 0.0.0.0，因此客户端必须在每个请求中发送 Authorization: Bearer <token>。该镜像允许将 localhost 和 127.0.0.1 作为 Host 值；如需使用其他值，请将 MCP_HTTP_ALLOWED_HOSTS 设置为你的公共主机名。

安全模型

• 不收集遥测数据。 服务不会发送分析或使用数据。它仅向 OpenSolar API 以及 OpenSolar 返回的文件和图片 URL 发送请求。
• 凭据由你掌控，进程由你运行。 令牌保留在你的环境或客户端配置中，不会持久化，本项目也不运行任何托管服务。
• 写入操作需明确执行。 修改类工具带有 MCP readOnlyHint: false 注解，破坏性工具带有 destructiveHint: true 注解，且不会自动重试。设置 OPENSOLAR_READ_ONLY=1 可彻底移除这些工具。
• 不猜测。 只有当搜索报告 resolution: unique，或在完整扫描中对单个完全匹配的电子邮件或电话号码报告 identifier_match_id 时，才会确认目标。服务不会重试写入操作，也不会公开隐藏的批量写入功能。
• 输出最少化。 已签名的下载 URL、集成密钥、Webhook 密钥、个人身份字段和原始设计数据都会被编辑或省略。
• 工作量有上限。 搜索、下载和 Raw Data 解压缩都设有固定限制。只有普通读取操作会重试，且仅在 HTTP 429 时最多重试三次。
• HTTP 模式会传递你的 OpenSolar 令牌。 客户端发送的 bearer 令牌就是 OpenSolar 令牌，会被转发给 OpenSolar。它不是 MCP OAuth 令牌。如果多人共用同一部署，请在其前方设置经过身份验证的网关。

请私下报告漏洞——详见 SECURITY.md。

兼容性

成功的结构化工具结果也会包含以精简 JSON 文本序列化的相同负载。因此，不转发 structuredContent 的客户端仍可将完整的结构化结果传递给模型。

故障排查

日志以 JSON 行的形式写入 stderr，因此 stdout 会保持干净，以供 MCP 协议使用。

开发

git clone https://github.com/Align-Software-Company/opensolar-mcp.git
cd opensolar-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm check:all      # repository hygiene, registry metadata, lint, typecheck, offline tests
pnpm build
pnpm test:docker    # build and smoke-test the Docker image

常规测试套件可离线运行。实时集成测试会读取 .env.local，且默认以只读模式运行；写入操作需要设置 OPENSOLAR_INTEGRATION_WRITES=1，并使用专用的测试记录：

pnpm test:integration
OPENSOLAR_INTEGRATION_WRITES=1 pnpm test:integration

提交拉取请求前，请阅读 CONTRIBUTING.md，尤其是 OpenSolar API 证据相关规则。

文档

贡献

欢迎贡献。请参阅 CONTRIBUTING.md 和行为准则。如遇安全问题，请按照 SECURITY.md 中的说明处理，不要提交 issue。

许可证

MIT © 2026 Align Software Company。

OpenSolar 是 OpenSolar Pty Ltd 的商标。本项目独立开发，未经 OpenSolar 认可。