@sport365/sport-mcp 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# Sport MCP
+
+Sport MCP is a Rust-based MCP stdio server packaged as an npm CLI. Users can start it with `npx`, while the actual MCP protocol handling and upstream API calls run in the native Rust binary.
+
+## Usage
+
+After the package is published, configure your MCP client like this:
+
+```json
+{
+  "mcpServers": {
+    "sport": {
+      "command": "npx",
+      "args": ["-y", "@sport365/sport-mcp"],
+      "env": {
+        "SPORT_AGENT_KEY": "skill_abc123"
+      }
+    }
+  }
+}
+```
+
+`SPORT_AGENT_KEY` is required. It is sent to the upstream API as `X-Agent-Key`.
+
+Optional environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SPORT_API_BASE_URL` | `https://beta-skill-api.zhitiyu.com/` | Override the upstream API host. |
+| `SPORT_API_TIMEOUT_SECS` | `20` | HTTP timeout in seconds. |
+| `X_AGENT_KEY` | none | Fallback when `SPORT_AGENT_KEY` is not set. |
+
+The default upstream URL is compiled into the Rust binary from `crates/sport-core/build.rs`.
+The API documentation entry is `https://beta-skill-api.zhitiyu.com/docs/api`.
+
+## MCP Tools
+
+The server exposes two MCP tools:
+
+| Tool | Description |
+| --- | --- |
+| `sport_list_domains` | List supported football and basketball API domains. |
+| `sport_api_call` | Call a whitelisted Skill API domain with query parameters. |
+
+Example `sport_api_call` input:
+
+```json
+{
+  "ball_type": "ft",
+  "kind": "data",
+  "domain": "match-info",
+  "query": {
+    "matchId": "123456"
+  }
+}
+```
+
+For material APIs, repeated query parameters can be passed as arrays:
+
+```json
+{
+  "ball_type": "bk",
+  "kind": "material",
+  "domain": "match",
+  "query": {
+    "matchId": "123456",
+    "materialIndexList": ["1", "3"]
+  }
+}
+```
+
+API references:
+
+- [Football API](docs/api/football-api.md)
+- [Basketball API](docs/api/basketball-api.md)
+
+## Project Structure
+
+```text
+bin/sport-mcp.js             npm/npx wrapper
+crates/sport-core            Core config, domain registry, HTTP client
+crates/sport-mcp-server      Rust MCP stdio server binary
+docs/architecture.md         Chinese architecture design
+docs/api/                    Skill API documents
+scripts/                     Build, staging and packaging scripts
+dist/                        Generated build and npm package output
+```
+
+Node only selects and starts the native binary. It does not parse MCP messages or call upstream APIs. The Rust server writes MCP JSON-RPC messages through stdio and writes normal logs to stderr.
+
+## Build
+
+Build the current platform:
+
+```bash
+npm run build
+```
+
+Build Windows x64 and Linux x64:
+
+```bash
+npm run build:win-linux
+```
+
+Build all supported native binaries:
+
+```bash
+npm run build:all
+```
+
+`build:all` currently stages:
+
+```text
+native/sport-mcp-server-win32-x64.exe
+native/sport-mcp-server-linux-x64
+native/sport-mcp-server-darwin-x64
+native/sport-mcp-server-darwin-arm64
+```
+
+On Windows, Linux x64 is built with Docker by default when Docker is available. macOS cross builds use `cargo-zigbuild`, Zig and a configured macOS SDK.
+
+## macOS Cross Build On Windows
+
+Required tools:
+
+```powershell
+choco install zig -y
+cargo install --locked cargo-zigbuild
+rustup target add x86_64-apple-darwin aarch64-apple-darwin
+```
+
+Configure the macOS SDK:
+
+```powershell
+$env:SDKROOT="D:\sdks\MacOSX.sdk"
+$env:MACOSX_SDK_PATH="D:\sdks\MacOSX.sdk"
+```
+
+Then build:
+
+```powershell
+npm run build:mac:zig
+```
+
+## Package
+
+Generate an npm tarball for the current platform:
+
+```bash
+npm run package
+```
+
+Generate a full-platform tarball:
+
+```bash
+npm run package:all
+```
+
+The output is written to:
+
+```text
+dist/artifacts/
+```
+
+The npm staging directory is:
+
+```text
+dist/npm/
+```
+
+## Publish
+
+Before publishing, replace the placeholder package name in `package.json`:
+
+```json
+{
+  "name": "@sport365/sport-mcp"
+}
+```
+
+Then publish the staged package:
+
+```bash
+npm login
+npm run publish:npm:all
+```
+
+## Architecture
+
+The detailed architecture design is written in Chinese:
+
+- [Architecture Design](docs/architecture.md)