mcp-server-sms 0.1.0__tar.gz

mcp_server_sms-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# stdio credentials; HTTP calls use their own Authorization header.
+VOLCENGINE_ACCESS_KEY=
+VOLCENGINE_SECRET_KEY=
+VOLCENGINE_SESSION_TOKEN=

mcp_server_sms-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.env
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

mcp_server_sms-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mcp_server_sms-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: mcp-server-sms
+Version: 0.1.0
+Summary: Stateless MCP tools for Volcengine SMS APIs
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp[cli]<3,>=2.2
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: starlette<2,>=0.47
+Requires-Dist: uvicorn<1,>=0.35
+Requires-Dist: volcengine<2,>=1.0.191
+Provides-Extra: test
+Requires-Dist: build>=1; extra == 'test'
+Requires-Dist: pytest-asyncio>=1; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff<1,>=0.16; extra == 'test'
+Requires-Dist: twine>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Volcengine SMS MCP Server
+
+[简体中文](README_zh.md)
+
+An independent adapter for Volcengine SMS APIs. Each tool receives its complete API input, makes one upstream request and returns the result. It supports MCP **2026-07-28**, stdio and **stateless Streamable HTTP**.
+
+There is no database, business cache, qualification draft, stored preview, generic execution ticket, local file service or UI. It does not load or depend on a Skill. The client owns interaction and user confirmation; the SMS service owns business validation, applications, tasks and delivery records.
+
+## Tools
+
+| Capability | Tools |
+| --- | --- |
+| Account and message groups | `list_message_groups`, `get_message_group`, `get_account_information` |
+| Qualifications | `get_qualification_requirements`, `list_qualifications`, `recognize_qualification_document`, `check_qualification_enterprise`, `check_qualification_person`, `apply_qualification` |
+| Mobile verification | `send_verification_code`, `verify_code` |
+| Signatures and templates | `list_signatures`, `apply_signature`, `list_templates`, `list_second_templates`, `apply_template` |
+| Sending and reports | `send_sms`, `list_send_logs`, `get_send_statistics` |
+| Ordinary batches | `get_batch_upload_url`, `get_batch_csv_template`, `create_batch_task`, `get_batch_task`, `list_batch_tasks`, `start_batch_task`, `cancel_batch_task` |
+
+There are **26 tools**. Ordinary batches cover domestic notification and marketing SMS. Special notification batches, OTP batches and international SMS are outside this server's scope.
+
+Tools preserve the upstream result structure and IDs. They do not select a template, rewrite content, deduplicate recipients, synthesize qualification-check tickets or decide whether a human approved an operation. A `ticket` returned by a qualification check is an upstream business receipt, not MCP state; the caller provides it when submitting the complete application. Client configuration must provide the application/scene/template values required by mobile verification APIs.
+
+Qualification images must already be available through the existing SMS material channel. OCR and application tools accept its file references; there is no MCP-owned `fileId`, filesystem access or upload endpoint. The client must arrange a private material channel and handle OCR results and personal information appropriately. For batches, `get_batch_upload_url` returns the upstream signed upload URL and `file` key: upload the CSV directly, then pass that key as `fileUrl` to `create_batch_task`. Creating a task does not start it.
+
+## Install and configure
+
+Python 3.11 or later is required. From source:
+
+```bash
+uv sync --extra test
+uv run mcp-server-sms --transport stdio
+```
+
+For stdio, supply `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY` and optionally `VOLCENGINE_SESSION_TOKEN` in the client process environment. No local subject, encryption key or database URL is required. Do not place credentials in prompts or source control.
+
+After version 0.1.0 has been published:
+
+```bash
+uvx --from 'mcp-server-sms==0.1.0' mcp-server-sms --transport stdio
+```
+
+Development clients can use an explicit wheel path before publication.
+
+## Streamable HTTP
+
+```bash
+mcp-server-sms --transport streamable-http --host 0.0.0.0 --port 8000 \
+  --public-url https://sms-mcp.example.com
+```
+
+Connect to `/mcp`. The deployment supplies HTTPS and access policy. Every HTTP request carries `Authorization: Bearer <Base64 JSON>` with the following credential fields:
+
+```json
+{"AccessKeyId":"<access-key>","SecretAccessKey":"<secret-key>","SessionToken":"<optional-session-token>"}
+```
+
+This follows the repository's credential-passing convention; it is **not an OAuth access token** and Base64 is not encryption. The client or trusted gateway must construct the header outside model context. HTTP never falls back to process credentials. Each SMS call uses these credentials for official V4 signing, and SMS/IAM enforces resource access. The server has no OAuth login flow or persistent caller identity.
+
+`--public-url` adds the deployment's HTTPS origin to DNS-rebinding protection. Without it, only local HTTP hosts are accepted. Requests do not require a protocol session or shared process state. Replicas can serve requests independently.
+
+The HTTP connection pool is owned by the MCP server lifespan and closed at shutdown. Credentials and signed headers remain per-request, and response cookies are not retained between callers. Connection reuse does not introduce business state or a database.
+
+## Outcomes and confirmation
+
+- The client must obtain user authorization before calling tools with side effects. Tool annotations describe behavior; they do not prove user consent.
+- SMS API acceptance and delivery are separate. Use the returned Message ID with `list_send_logs`; an empty result does not prove failure.
+- Application creation is not audit approval. Query qualification, signature or template state separately.
+- No API calls are automatically retried. A timeout or unconfirmed write returns `outcome_unknown`; do not blindly repeat it. This adapter does not provide durable request deduplication or an exactly-once guarantee.
+- Unstructured HTTP 400/401/403/404/405/413/415/422/429 responses are explicit rejections. Other unstructured statuses, server errors, and malformed or incomplete successful write responses remain uncertain. API-response errors include `http_status` without echoing the response body.
+- The upload API's top-level `url` is returned byte-for-byte, including its signed credential parameters. Other fields still undergo credential redaction. Treat the complete URL as a temporary capability; do not redact it before upload or expose it in logs.
+- A successful API call can contain a failed business check, such as an invalid verification code. Inspect the upstream `status` value.
+- The API adapter does not log request bodies or credentials. Upstream error text is not echoed, and authentication fields are removed from results; ordinary business content is preserved. Clients and deployment platforms must also configure their own logging and private-data handling.
+
+## Development
+
+```bash
+uv sync --extra test
+uv run ruff check src tests
+uv run pytest -q
+uv build
+uv run python -m twine check dist/*
+```
+
+Tests cover direct API calls, request serialization, credential isolation, uncertain writes, business error responses, file-response decoding and the stateless protocol. They do not submit real qualifications or send real SMS. Actual write tests require separate customer authorization.
+
+API fields are checked against the [official SMS SDK](https://github.com/volcengine/volcengine-python-sdk/tree/3b116781c5b8bb648f215b29587f2ec74d9e5d02/volcenginesdkvolcsms). V4 signing uses the [official Python SDK](https://github.com/volcengine/volc-sdk-python). Qualification extension APIs use the existing SMS service contract; SDK coverage and account availability must be verified for the deployment.
+
+The repository's package workflow builds PRs and publishes new versions after merge, with maintainer PyPI permissions. Package publication does not deploy a cloud service. Licensed under Apache-2.0.

mcp_server_sms-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Volcengine SMS MCP Server
+
+[简体中文](README_zh.md)
+
+An independent adapter for Volcengine SMS APIs. Each tool receives its complete API input, makes one upstream request and returns the result. It supports MCP **2026-07-28**, stdio and **stateless Streamable HTTP**.
+
+There is no database, business cache, qualification draft, stored preview, generic execution ticket, local file service or UI. It does not load or depend on a Skill. The client owns interaction and user confirmation; the SMS service owns business validation, applications, tasks and delivery records.
+
+## Tools
+
+| Capability | Tools |
+| --- | --- |
+| Account and message groups | `list_message_groups`, `get_message_group`, `get_account_information` |
+| Qualifications | `get_qualification_requirements`, `list_qualifications`, `recognize_qualification_document`, `check_qualification_enterprise`, `check_qualification_person`, `apply_qualification` |
+| Mobile verification | `send_verification_code`, `verify_code` |
+| Signatures and templates | `list_signatures`, `apply_signature`, `list_templates`, `list_second_templates`, `apply_template` |
+| Sending and reports | `send_sms`, `list_send_logs`, `get_send_statistics` |
+| Ordinary batches | `get_batch_upload_url`, `get_batch_csv_template`, `create_batch_task`, `get_batch_task`, `list_batch_tasks`, `start_batch_task`, `cancel_batch_task` |
+
+There are **26 tools**. Ordinary batches cover domestic notification and marketing SMS. Special notification batches, OTP batches and international SMS are outside this server's scope.
+
+Tools preserve the upstream result structure and IDs. They do not select a template, rewrite content, deduplicate recipients, synthesize qualification-check tickets or decide whether a human approved an operation. A `ticket` returned by a qualification check is an upstream business receipt, not MCP state; the caller provides it when submitting the complete application. Client configuration must provide the application/scene/template values required by mobile verification APIs.
+
+Qualification images must already be available through the existing SMS material channel. OCR and application tools accept its file references; there is no MCP-owned `fileId`, filesystem access or upload endpoint. The client must arrange a private material channel and handle OCR results and personal information appropriately. For batches, `get_batch_upload_url` returns the upstream signed upload URL and `file` key: upload the CSV directly, then pass that key as `fileUrl` to `create_batch_task`. Creating a task does not start it.
+
+## Install and configure
+
+Python 3.11 or later is required. From source:
+
+```bash
+uv sync --extra test
+uv run mcp-server-sms --transport stdio
+```
+
+For stdio, supply `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY` and optionally `VOLCENGINE_SESSION_TOKEN` in the client process environment. No local subject, encryption key or database URL is required. Do not place credentials in prompts or source control.
+
+After version 0.1.0 has been published:
+
+```bash
+uvx --from 'mcp-server-sms==0.1.0' mcp-server-sms --transport stdio
+```
+
+Development clients can use an explicit wheel path before publication.
+
+## Streamable HTTP
+
+```bash
+mcp-server-sms --transport streamable-http --host 0.0.0.0 --port 8000 \
+  --public-url https://sms-mcp.example.com
+```
+
+Connect to `/mcp`. The deployment supplies HTTPS and access policy. Every HTTP request carries `Authorization: Bearer <Base64 JSON>` with the following credential fields:
+
+```json
+{"AccessKeyId":"<access-key>","SecretAccessKey":"<secret-key>","SessionToken":"<optional-session-token>"}
+```
+
+This follows the repository's credential-passing convention; it is **not an OAuth access token** and Base64 is not encryption. The client or trusted gateway must construct the header outside model context. HTTP never falls back to process credentials. Each SMS call uses these credentials for official V4 signing, and SMS/IAM enforces resource access. The server has no OAuth login flow or persistent caller identity.
+
+`--public-url` adds the deployment's HTTPS origin to DNS-rebinding protection. Without it, only local HTTP hosts are accepted. Requests do not require a protocol session or shared process state. Replicas can serve requests independently.
+
+The HTTP connection pool is owned by the MCP server lifespan and closed at shutdown. Credentials and signed headers remain per-request, and response cookies are not retained between callers. Connection reuse does not introduce business state or a database.
+
+## Outcomes and confirmation
+
+- The client must obtain user authorization before calling tools with side effects. Tool annotations describe behavior; they do not prove user consent.
+- SMS API acceptance and delivery are separate. Use the returned Message ID with `list_send_logs`; an empty result does not prove failure.
+- Application creation is not audit approval. Query qualification, signature or template state separately.
+- No API calls are automatically retried. A timeout or unconfirmed write returns `outcome_unknown`; do not blindly repeat it. This adapter does not provide durable request deduplication or an exactly-once guarantee.
+- Unstructured HTTP 400/401/403/404/405/413/415/422/429 responses are explicit rejections. Other unstructured statuses, server errors, and malformed or incomplete successful write responses remain uncertain. API-response errors include `http_status` without echoing the response body.
+- The upload API's top-level `url` is returned byte-for-byte, including its signed credential parameters. Other fields still undergo credential redaction. Treat the complete URL as a temporary capability; do not redact it before upload or expose it in logs.
+- A successful API call can contain a failed business check, such as an invalid verification code. Inspect the upstream `status` value.
+- The API adapter does not log request bodies or credentials. Upstream error text is not echoed, and authentication fields are removed from results; ordinary business content is preserved. Clients and deployment platforms must also configure their own logging and private-data handling.
+
+## Development
+
+```bash
+uv sync --extra test
+uv run ruff check src tests
+uv run pytest -q
+uv build
+uv run python -m twine check dist/*
+```
+
+Tests cover direct API calls, request serialization, credential isolation, uncertain writes, business error responses, file-response decoding and the stateless protocol. They do not submit real qualifications or send real SMS. Actual write tests require separate customer authorization.
+
+API fields are checked against the [official SMS SDK](https://github.com/volcengine/volcengine-python-sdk/tree/3b116781c5b8bb648f215b29587f2ec74d9e5d02/volcenginesdkvolcsms). V4 signing uses the [official Python SDK](https://github.com/volcengine/volc-sdk-python). Qualification extension APIs use the existing SMS service contract; SDK coverage and account availability must be verified for the deployment.
+
+The repository's package workflow builds PRs and publishes new versions after merge, with maintainer PyPI permissions. Package publication does not deploy a cloud service. Licensed under Apache-2.0.

mcp_server_sms-0.1.0/README_zh.md

@@ -0,0 +1,116 @@
+# 火山引擎短信 MCP Server
+
+[English](README.md)
+
+独立的短信 API 适配服务，支持 **MCP 2026-07-28**、stdio 和 **Stateless Streamable HTTP**。每个工具接收完整参数，调用一次对应短信接口并返回结果。
+
+不依赖 Skill，不保存业务草稿或预览，不提供页面、本地文件服务及通用 `prepare/execute` 流程；不需要 SQLite、PostgreSQL、Redis 或业务加密密钥。客户端负责交互和用户确认，现有短信服务负责业务校验、申请、任务与发送记录。
+
+## 工具与接口
+
+| 工具 | 短信 Action |
+| --- | --- |
+| `list_message_groups` | `ListSubAccountForAgent` |
+| `get_message_group` | `GetSubAccountDetail` |
+| `get_account_information` | `ListAllSmsProduct` |
+| `get_qualification_requirements` | `GetAccountIdentRankForAgent` |
+| `list_qualifications` | `GetSignatureIdentificationList` |
+| `recognize_qualification_document` | `GetOCRLicenseForAgent` |
+| `check_qualification_enterprise` | `ThreeElementEnterpriseCheckForAgent` |
+| `check_qualification_person` | `ThreeElementPersonCheckForAgent` |
+| `send_verification_code` | `SendSmsVerifyCodeByMobile` |
+| `verify_code` | `CheckSmsVerifyCodeByMobile` |
+| `apply_qualification` | `ApplySignatureIdentificationForAgent` |
+| `list_signatures` | `ListSignatureForAgent` |
+| `apply_signature` | `ApplySmsSignatureV2` |
+| `list_templates` | `ListSmsTemplateForAgent` |
+| `list_second_templates` | `ListSecondTemplate` |
+| `apply_template` | `ApplySmsTemplateV2` |
+| `send_sms` | `SendSmsForAgent` |
+| `list_send_logs` | `ListSmsSendLogForAgent` |
+| `get_send_statistics` | `ListTotalSendCountStatForAgent` |
+| `get_batch_upload_url` | `GetUploadTosURL` |
+| `get_batch_csv_template` | `TemplateUploadDemo` |
+| `create_batch_task` | `SetBatchTask` |
+| `get_batch_task` | `GetBatchTaskDetail` |
+| `list_batch_tasks` | `GetBatchTaskList` |
+| `start_batch_task` | `ConsentBatchTask` |
+| `cancel_batch_task` | `DeleteBatchTask` |
+
+共 26 个工具。普通群发仅覆盖国内通知和营销短信，不包含特殊通知群发、验证码群发或国际短信。服务开通由用户在[短信控制台](https://console.volcengine.com/sms)阅读协议并完成；`RE:0001` 表示未开通。
+
+工具不替换签名、不匹配或改写模板、不去重号码，也不生成跳过校验票据。已有模板 ID 直接交给发送接口校验，不因查询列表缺少某类模板就自行禁止发送。
+
+## 资质与文件
+
+资质申请接收完整企业、经办人、责任人、可选法人信息、材料引用和上游校验票据。`ticket` 是短信校验接口返回的业务凭据，由客户端保管并在申请时传回，不是 MCP 的草稿 ID。上游要求、票据有效性和审核结果由短信服务判断。
+
+验证码接口所需的应用 ID、场景、模板和通道来自已有业务配置，MCP 不硬编码某个内部应用或自动选择。客户端应通过私密渠道提供个人材料和验证码；OCR 返回识别字段，由客户核对后决定提交内容。
+
+资质材料应先通过现有短信材料渠道上传，OCR 和申请工具接收该渠道的文件引用。MCP 不读取本机路径、不下载任意 URL、不托管文件，也不提供额外的 `/files` 接口。实际客户端须具备可用的私密材料渠道，普通聊天附件不会自动转换成短信材料引用。
+
+群发 CSV：调用 `get_batch_upload_url`，客户端使用短期签名 URL 直接上传原文件，再把返回的 `file` 对象 Key 作为 `fileUrl` 传入 `create_batch_task`。创建与启动是短信业务本身的两个操作，必须分别调用。
+
+## 本地运行
+
+需要 Python 3.11 或以上版本。配置 `VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY` 及可选 `VOLCENGINE_SESSION_TOKEN`，再运行：
+
+```bash
+uv sync --extra test
+uv run mcp-server-sms --transport stdio
+```
+
+凭据放在客户端进程环境中，不放入工具参数、聊天或仓库。无需配置数据库、流程有效期、本地身份或材料目录。
+
+0.1.0 发布后可使用固定版本：
+
+```bash
+uvx --from 'mcp-server-sms==0.1.0' mcp-server-sms --transport stdio
+```
+
+发布前可以从源码或指定 wheel 安装。
+
+## 云端运行
+
+```bash
+mcp-server-sms --transport streamable-http --host 0.0.0.0 --port 8000 \
+  --public-url https://sms-mcp.example.com
+```
+
+客户端连接 `/mcp`。部署平台提供 HTTPS 和访问策略，每个请求通过 `Authorization: Bearer <Base64 JSON>` 传递短信凭据：
+
+```json
+{"AccessKeyId":"<access-key>","SecretAccessKey":"<secret-key>","SessionToken":"<optional-session-token>"}
+```
+
+这沿用仓库已有的凭据传递方式，**不是 OAuth access token，Base64 也不是加密**。由客户端或可信网关在模型之外构造请求头，不得写入访问日志。每次短信请求独立执行官方 V4 签名，由短信/IAM 校验权限；HTTP 缺少凭据时不会使用进程默认账号。
+
+不创建 OAuth 登录应用，不保存用户身份。`--public-url` 用于配置 HTTP 域名校验；未提供时仅允许本机域名。无需协议会话或共享存储，多副本可以独立处理请求。云端平台的实际请求头与材料渠道仍需联调确认。
+
+HTTP 连接池随 MCP 服务启动和关闭，凭据和签名头仍逐请求生成，不保留不同调用者之间的响应 Cookie。连接复用不引入业务状态或数据库。
+
+## 执行语义
+
+- 写工具直接产生业务操作，客户端必须先取得用户授权；工具注解不是授权证明。
+- 发送接口成功只表示受理，需按 Message ID 查询送达回执。空列表不是失败证据。
+- 资质、签名和模板申请成功不等于审核通过，分别查询其状态。
+- 不自动重试任何 API 调用。写请求超时或响应不足以确认结果时返回 `outcome_unknown`，不能盲目重发；不承诺跨请求去重或“恰好一次”。
+- 非结构化的 HTTP 400/401/403/404/405/413/415/422/429 响应按明确拒绝处理；其他非结构化状态、服务端异常和损坏或缺少关键结果的成功响应，仍保留未知写结果。API 响应错误携带 `http_status`，不回显响应正文。
+- 上传接口顶层 `url` 保持完整原文，包括参与签名的凭证参数；其他字段仍按规则脱敏。完整 URL 是短期授权信息，不要修改后上传，也不要写入日志。
+- 接口调用成功也可能返回校验未通过，例如验证码的 `status` 非零；保留上游字段，调用方应检查业务结果。
+- 错误保留公开错误码和 RequestId，不回显请求正文、验证码、凭据或原始服务端错误文本；正常业务数据不做无声改写。
+
+## 验证和发布
+
+```bash
+uv run ruff check src tests
+uv run pytest -q
+uv build
+uv run python -m twine check dist/*
+```
+
+测试覆盖直接调用、参数映射、调用者凭据隔离、未知写结果、业务错误、CSV 响应及无状态协议；不会真的发送短信或提交申请。实际写操作验收需要客户单独授权，旧实现的测试结果不能代表本版已完成全流程验收。
+
+请求字段参照[官方短信 SDK](https://github.com/volcengine/volcengine-python-sdk/tree/3b116781c5b8bb648f215b29587f2ec74d9e5d02/volcenginesdkvolcsms)，请求签名使用[官方 Python SDK](https://github.com/volcengine/volc-sdk-python)。资质扩展 Action 按现有短信服务契约接入，需确认部署账号的接口可用性。
+
+包版本为 0.1.0，尚未发布。复用仓库现有 PR 构建检查和合入后的 PyPI 发布流程，发布权限由维护者提供；包发布不等于云端部署。许可证为 Apache-2.0。

mcp_server_sms-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "mcp-server-sms"
+version = "0.1.0"
+description = "Stateless MCP tools for Volcengine SMS APIs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+dependencies = [
+    "mcp[cli]>=2.2,<3",
+    "pydantic>=2.11,<3",
+    "httpx>=0.28,<1",
+    "starlette>=0.47,<2",
+    "uvicorn>=0.35,<1",
+    "volcengine>=1.0.191,<2",
+]
+
+[project.scripts]
+mcp-server-sms = "mcp_server_sms.server:main"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=1", "build>=1", "twine>=6", "ruff>=0.16,<1"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_server_sms"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]

mcp_server_sms-0.1.0/src/mcp_server_sms/__init__.py

@@ -0,0 +1,3 @@
+"""Volcengine SMS API tools for MCP."""
+
+__version__ = "0.1.0"

mcp_server_sms-0.1.0/src/mcp_server_sms/auth.py

@@ -0,0 +1,46 @@
+"""Per-call credentials. HTTP never falls back to the server's environment."""
+
+import base64
+import binascii
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+class AuthenticationError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, repr=False)
+class Credentials:
+    access_key: str
+    secret_key: str
+    session_token: str = ""
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str] | None):
+        if headers is None:
+            values = {
+                "AccessKeyId": os.getenv("VOLCENGINE_ACCESS_KEY"),
+                "SecretAccessKey": os.getenv("VOLCENGINE_SECRET_KEY"),
+                "SessionToken": os.getenv("VOLCENGINE_SESSION_TOKEN", ""),
+            }
+        else:
+            authorization = headers.get("authorization", "")
+            scheme, separator, encoded = authorization.partition(" ")
+            if not separator or scheme.lower() != "bearer" or len(encoded) > 16384:
+                raise AuthenticationError("需要 Authorization: Bearer <Base64 JSON 短信凭据>")
+            try:
+                values = json.loads(base64.b64decode(encoded, validate=True))
+            except (ValueError, UnicodeError, binascii.Error):
+                raise AuthenticationError("短信调用凭据格式无效") from None
+        if not isinstance(values, dict) or any(
+            not isinstance(values.get(key), str) or not values[key]
+            for key in ("AccessKeyId", "SecretAccessKey")
+        ):
+            raise AuthenticationError("需要完整的短信 AccessKeyId 和 SecretAccessKey")
+        token = values.get("SessionToken", "")
+        if not isinstance(token, str):
+            raise AuthenticationError("SessionToken 必须是字符串")
+        return cls(values["AccessKeyId"], values["SecretAccessKey"], token)