@sport365/sport-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,16 +2,25 @@
 
 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
+## Quick Start
 
-After the package is published, configure your MCP client like this:
+Sport MCP is a stdio MCP server. It should be started by an MCP client. Running `npx @sport365/sport-mcp` directly in a terminal only starts the stdio server and waits for MCP JSON-RPC messages.
+
+Check the package:
+
+```bash
+npx -y @sport365/sport-mcp@latest --version
+npx -y @sport365/sport-mcp@latest --help
+```
+
+Configure your MCP client like this:
 
 ```json
 {
   "mcpServers": {
     "sport": {
       "command": "npx",
-      "args": ["-y", "@sport365/sport-mcp"],
+      "args": ["-y", "@sport365/sport-mcp@latest"],
       "env": {
         "SPORT_AGENT_KEY": "skill_abc123"
       }
@@ -20,7 +29,9 @@ After the package is published, configure your MCP client like this:
 }
 ```
 
-`SPORT_AGENT_KEY` is required. It is sent to the upstream API as `X-Agent-Key`.
+`SPORT_AGENT_KEY` is required when calling `sport_api_call`. It is sent to the upstream API as `X-Agent-Key`. The server can still start without it, and `sport_list_domains` remains available for checking supported domains.
+
+For Claude Desktop, add the same JSON object under `mcpServers` in the Claude Desktop config file, then restart Claude Desktop. For Cursor or other MCP clients, use the same `command`, `args`, and `env` fields in that client's MCP server configuration UI.
 
 Optional environment variables:
 
@@ -33,6 +44,19 @@ Optional environment variables:
 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`.
 
+## Troubleshooting
+
+If the MCP client reports the server as unavailable:
+
+- Confirm the command is `npx`, not `node`.
+- Confirm args are `["-y", "@sport365/sport-mcp@latest"]`.
+- Confirm `SPORT_AGENT_KEY` is configured in the MCP client env when calling `sport_api_call`.
+- Restart the MCP client after editing its config.
+- Run `npx -y @sport365/sport-mcp@latest --help` to print the expected config.
+- Run `npm view @sport365/sport-mcp version` to confirm npm can see the package.
+
+If `sport_list_domains` works but `sport_api_call` returns a missing key error, the server is installed correctly and only the `SPORT_AGENT_KEY` env value is missing or not visible to the MCP client process.
+
 ## MCP Tools
 
 The server exposes two MCP tools:
@@ -170,7 +194,7 @@ dist/npm/
 
 ## Publish
 
-Before publishing, replace the placeholder package name in `package.json`:
+The package name is already configured as:
 
 ```json
 {
@@ -178,13 +202,21 @@ Before publishing, replace the placeholder package name in `package.json`:
 }
 ```
 
-Then publish the staged package:
+Build the full-platform package first:
 
 ```bash
 npm login
-npm run publish:npm:all
+npm run package:all
 ```
 
+Then publish the staged package:
+
+```bash
+npm publish ./dist/npm --access public
+```
+
+If the npm account uses WebAuthn, passkey, security key, Chrome, or Windows Hello for 2FA, do not pass `--otp`. The npm CLI will print a browser verification URL. Open it in Chrome, complete Windows Hello or security key verification, then paste the returned token back into the terminal.
+
 ## Architecture
 
 The detailed architecture design is written in Chinese:

package/bin/sport-mcp.js

@@ -6,6 +6,52 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJsonPath = path.join(root, "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`Sport MCP ${packageJson.version}
+
+Sport MCP is a stdio MCP server. It should be configured in an MCP client, not used as a normal HTTP CLI.
+
+MCP client config:
+
+{
+  "mcpServers": {
+    "sport": {
+      "command": "npx",
+      "args": ["-y", "@sport365/sport-mcp@latest"],
+      "env": {
+        "SPORT_AGENT_KEY": "skill_abc123"
+      }
+    }
+  }
+}
+
+Environment:
+  SPORT_AGENT_KEY          Required when calling sport_api_call. Sent as X-Agent-Key.
+  SPORT_API_BASE_URL       Optional. Defaults to https://beta-skill-api.zhitiyu.com/
+  SPORT_API_TIMEOUT_SECS   Optional. Defaults to 20.
+  X_AGENT_KEY              Optional fallback for SPORT_AGENT_KEY.
+
+Tools:
+  sport_list_domains       List supported football and basketball API domains.
+  sport_api_call           Call a documented Skill API domain.
+
+Manual checks:
+  npx -y @sport365/sport-mcp --version
+  npx -y @sport365/sport-mcp --help
+
+If an MCP client reports this server as unavailable, check that the client config uses command "npx",
+passes args ["-y", "@sport365/sport-mcp@latest"], and includes SPORT_AGENT_KEY in env.`);
+  process.exit(0);
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(packageJson.version);
+  process.exit(0);
+}
 
 const platform = process.platform;
 const arch = process.arch;

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "@sport365/sport-mcp",
-  "version": "0.1.0",
-  "description": "MCP server wrapper for Skill sport APIs.",
-  "type": "module",
-  "bin": {
-    "sport-mcp": "bin/sport-mcp.js"
-  },
-  "files": [
-    "bin",
-    "native",
-    "README.md",
-    "basketball-api.md",
-    "football-api.md"
-  ],
-  "scripts": {
-    "build": "node ./scripts/build-package.js",
-    "build:linux": "node ./scripts/build-package.js --target linux-x64",
-    "build:linux:cross": "node ./scripts/build-package.js --target linux-x64 --linux-builder cargo",
-    "build:linux:docker": "node ./scripts/build-package.js --target linux-x64 --linux-builder docker",
-    "build:mac": "node ./scripts/build-package.js --targets mac",
-    "build:mac:zig": "node ./scripts/build-package.js --targets mac --mac-builder zig",
-    "build:mac:x64": "node ./scripts/build-package.js --target darwin-x64",
-    "build:mac:arm64": "node ./scripts/build-package.js --target darwin-arm64",
-    "build:win-linux": "node ./scripts/build-package.js --targets win-linux",
-    "build:all": "node ./scripts/build-package.js --targets all",
-    "package": "npm run build && node ./scripts/pack-npm.js",
-    "package:linux": "npm run build:linux && node ./scripts/pack-npm.js",
-    "package:linux:cross": "npm run build:linux:cross && node ./scripts/pack-npm.js",
-    "package:linux:docker": "npm run build:linux:docker && node ./scripts/pack-npm.js",
-    "package:mac": "npm run build:mac && node ./scripts/pack-npm.js",
-    "package:mac:zig": "npm run build:mac:zig && node ./scripts/pack-npm.js",
-    "package:mac:x64": "npm run build:mac:x64 && node ./scripts/pack-npm.js",
-    "package:mac:arm64": "npm run build:mac:arm64 && node ./scripts/pack-npm.js",
-    "package:win-linux": "npm run build:win-linux && node ./scripts/pack-npm.js",
-    "package:all": "npm run build:all && node ./scripts/pack-npm.js",
-    "pack": "npm run package",
-    "publish:npm": "npm run build && npm publish ./dist/npm --access public",
-    "publish:npm:all": "npm run build:all && npm publish ./dist/npm --access public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT"
-}
+{
+  "name": "@sport365/sport-mcp",
+  "version": "0.1.1",
+  "description": "MCP server wrapper for Skill sport APIs.",
+  "type": "module",
+  "bin": {
+    "sport-mcp": "bin/sport-mcp.js"
+  },
+  "files": [
+    "bin",
+    "native",
+    "README.md",
+    "basketball-api.md",
+    "football-api.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build-package.js",
+    "build:linux": "node ./scripts/build-package.js --target linux-x64",
+    "build:linux:cross": "node ./scripts/build-package.js --target linux-x64 --linux-builder cargo",
+    "build:linux:docker": "node ./scripts/build-package.js --target linux-x64 --linux-builder docker",
+    "build:mac": "node ./scripts/build-package.js --targets mac",
+    "build:mac:zig": "node ./scripts/build-package.js --targets mac --mac-builder zig",
+    "build:mac:x64": "node ./scripts/build-package.js --target darwin-x64",
+    "build:mac:arm64": "node ./scripts/build-package.js --target darwin-arm64",
+    "build:win-linux": "node ./scripts/build-package.js --targets win-linux",
+    "build:all": "node ./scripts/build-package.js --targets all",
+    "package": "npm run build && node ./scripts/pack-npm.js",
+    "package:linux": "npm run build:linux && node ./scripts/pack-npm.js",
+    "package:linux:cross": "npm run build:linux:cross && node ./scripts/pack-npm.js",
+    "package:linux:docker": "npm run build:linux:docker && node ./scripts/pack-npm.js",
+    "package:mac": "npm run build:mac && node ./scripts/pack-npm.js",
+    "package:mac:zig": "npm run build:mac:zig && node ./scripts/pack-npm.js",
+    "package:mac:x64": "npm run build:mac:x64 && node ./scripts/pack-npm.js",
+    "package:mac:arm64": "npm run build:mac:arm64 && node ./scripts/pack-npm.js",
+    "package:win-linux": "npm run build:win-linux && node ./scripts/pack-npm.js",
+    "package:all": "npm run build:all && node ./scripts/pack-npm.js",
+    "pack": "npm run package",
+    "publish:npm": "npm run build && npm publish ./dist/npm --access public",
+    "publish:npm:all": "npm run build:all && npm publish ./dist/npm --access public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}