From f9d266d3abf5ce26e43d6fa50340d804879d4aca Mon Sep 17 00:00:00 2001 From: Devid HW Date: Wed, 22 Apr 2026 07:20:03 +0700 Subject: [PATCH] =?UTF-8?q?docs:=20clean=20up=20public=20repo=20=E2=80=94?= =?UTF-8?q?=20remove=20IDE=20files,=20fix=20stale=20refs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Untrack .claude/commands/ and .windsurf/workflows/ (personal IDE config) - Fix .gitignore: scope /CLAUDE.md to root only, add .claude/, remove incorrect .github/workflows/ exclusion (CI needs these tracked) - Rename docs/ANTIGRAVITY.md → docs/CLAUDE.md (Claude Desktop setup; "Antigravity" was an internal codename, confusing to public users) - Fix stale repo name: masdevid/mt5-mcp → masdevid/mt5-quant in README.md, docs/CLAUDE.md, CURSOR.md, QUICKSTART.md, VSCODE.md, WINDSURF.md Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/release.md | 114 -------------------------- .gitignore | 6 +- .windsurf/workflows/release.md | 113 ------------------------- README.md | 6 +- docs/ANTIGRAVITY.md | 145 --------------------------------- docs/CLAUDE.md | 138 +++++++++++++++++++++++++++++++ docs/CURSOR.md | 4 +- docs/QUICKSTART.md | 12 +-- docs/VSCODE.md | 4 +- docs/WINDSURF.md | 4 +- 10 files changed, 155 insertions(+), 391 deletions(-) delete mode 100644 .claude/commands/release.md delete mode 100644 .windsurf/workflows/release.md delete mode 100644 docs/ANTIGRAVITY.md create mode 100644 docs/CLAUDE.md diff --git a/.claude/commands/release.md b/.claude/commands/release.md deleted file mode 100644 index 35233ed..0000000 --- a/.claude/commands/release.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -description: Release a new version of mt5-quant — bump, changelog, tag, push ---- - -# /release — MT5-Quant Release Workflow - -Automates the full release cycle: version bump → changelog → git tag → GitHub push → CI triggers build + MCP publish. - -## Usage - -``` -/release [patch|minor|major|X.Y.Z] -``` - -Default is `patch` if no argument is given. - ---- - -## Step 1 — Check current version and state - -```bash -grep '^version' Cargo.toml | head -1 -git status --short -git log --oneline -5 -``` - -## Step 2 — Count tools (update docs if needed) - -```bash -grep -r "pub fn tool_" src/tools/definitions/ | wc -l -``` - -If the count changed since the last release, update: -- `README.md` — "MCP Tools (N)" section header and description -- `docs/MCP_TOOLS.md` — "documents X of Y total tools" line - -## Step 3 — Run the release script - -```bash -bash scripts/release.sh patch -``` - -Replace `patch` with `minor`, `major`, or an explicit version like `1.33.0`. - -The script will: -1. Bump `Cargo.toml` version -2. Update `server.json` version + download URL (SHA256 = TBD, set by CI) -3. Generate a `CHANGELOG.md` entry from `git log` since the last tag -4. Run `cargo check` to verify the build -5. Commit all changes -6. Create an annotated git tag -7. Push branch + tag → triggers GitHub Actions - -## Step 4 — Monitor GitHub Actions - -```bash -gh run list --limit 5 -``` - -Or open: https://github.com/masdevid/mt5-quant/actions - -The CI pipeline will: -- Build macOS arm64 + Linux x64 binaries -- Create the GitHub Release with both artifacts -- Build the MCP installable package -- Compute the real SHA256 and commit it back to `server.json` -- Attempt to publish to the MCP Registry - -## Step 5 — Install updated binary locally - -```bash -cp target/release/mt5-quant ~/.local/bin/mt5-quant -``` - -Or rebuild from the release tag: - -```bash -cargo build --release && cp target/release/mt5-quant ~/.local/bin/mt5-quant -``` - -## Step 6 — Verify MCP registration - -```bash -claude mcp list -~/.local/bin/mt5-quant --help 2>/dev/null || echo "binary works" -``` - ---- - -## Troubleshooting - -**MCP publish failed in CI?** - -```bash -# Download latest mcp-publisher -curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz -./mcp-publisher login github -./mcp-publisher publish -``` - -**Need to re-run CI without a new tag?** - -```bash -gh workflow run release.yml -f version=v1.32.0 -``` - -**Rollback a bad release?** - -```bash -git tag -d v1.32.0 -git push origin :refs/tags/v1.32.0 -# Then delete the GitHub Release via web UI or: -gh release delete v1.32.0 -``` diff --git a/.gitignore b/.gitignore index 870ae5f..8eb9459 100644 --- a/.gitignore +++ b/.gitignore @@ -20,14 +20,12 @@ config/baseline.json config/backtest_history.json # Claude Code (personal, not for repo) -CLAUDE.md +/CLAUDE.md +.claude/ # Windsurf (local workflows, not for repo) .windsurf/ -# GitHub Actions (local workflows, not for repo) -.github/workflows/ - # macOS .DS_Store diff --git a/.windsurf/workflows/release.md b/.windsurf/workflows/release.md deleted file mode 100644 index bb1e047..0000000 --- a/.windsurf/workflows/release.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -description: Release workflow — bump version, build, tag, push, publish MCP -tags: [release, publish, workflow] ---- - -# MT5-Quant Release Workflow - -One-command release: `bash scripts/release.sh [patch|minor|major|X.Y.Z]` - ---- - -## 0. Pre-release checklist - -- [ ] Features implemented and tested -- [ ] Docs updated (README.md, docs/MCP_TOOLS.md) with correct tool count -- [ ] `cargo check` passes - -Check tool count: - -// turbo -```bash -grep -r "pub fn tool_" src/tools/definitions/ | wc -l -``` - ---- - -## 1. Run the release script - -// turbo -```bash -bash scripts/release.sh patch -``` - -Accepts: `patch` · `minor` · `major` · `1.32.0` · `v1.32.0` - -The script handles: -- Version bump in `Cargo.toml` -- `server.json` version + download URL update -- `CHANGELOG.md` entry generation from git log -- `cargo check` verification -- Release commit + annotated git tag -- `git push` → triggers GitHub Actions - ---- - -## 2. Monitor CI - -// turbo -```bash -gh run list --limit 3 -``` - -CI pipeline stages: -1. **build-macos** / **build-linux** — parallel Rust builds with cache -2. **release** — creates GitHub Release with both binaries -3. **build-mcp-package** — packages binary + config + docs, computes SHA256 -4. **update-server-json** — commits real SHA256 back to `server.json` on master -5. **mcp-publish** — publishes to MCP Registry via GitHub OIDC -6. **release-info** — prints registration commands for all MCP clients - ---- - -## 3. Install locally - -// turbo -```bash -cp target/release/mt5-quant ~/.local/bin/mt5-quant -``` - ---- - -## 4. Verify - -// turbo -```bash -claude mcp list -``` - ---- - -## Manual MCP publish (if CI publish fails) - -// turbo -```bash -# Get latest mcp-publisher -LATEST=$(curl -sf https://api.github.com/repos/modelcontextprotocol/registry/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'])") -VERSION="${LATEST#v}" -curl -fsSL -o pub.tar.gz "https://github.com/modelcontextprotocol/registry/releases/download/${LATEST}/mcp-publisher_${VERSION}_$(uname -s | tr '[:upper:]' '[:lower:]')_amd64.tar.gz" -tar -xzf pub.tar.gz && chmod +x mcp-publisher -./mcp-publisher login github -./mcp-publisher publish -``` - ---- - -## Re-trigger CI without a new tag - -// turbo -```bash -gh workflow run release.yml -f version=v1.32.0 -``` - ---- - -## Rollback - -```bash -# Remove tag locally and remotely -git tag -d v1.32.0 -git push origin :refs/tags/v1.32.0 -# Delete GitHub Release -gh release delete v1.32.0 --yes -``` diff --git a/README.md b/README.md index 44437e3..f67b9e8 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Claude: [compile → clean → backtest → analyze 1,847 deals] ### 1. Download & Setup ```bash -curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz +curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz tar -xzf mt5.tar.gz bash scripts/setup.sh ``` @@ -40,7 +40,7 @@ bash scripts/setup.sh | **Windsurf** | Edit `~/.codeium/windsurf/mcp_config.json` | [WINDSURF.md →](docs/WINDSURF.md) | | **Cursor** | Edit `~/.cursor/mcp.json` or use Settings → MCP | [CURSOR.md →](docs/CURSOR.md) | | **VS Code** | Edit `.vscode/mcp.json` or run `MCP: Add Server` | [VSCODE.md →](docs/VSCODE.md) | -| **Antigravity** | Agent Panel → ... → MCP Servers → Edit configuration | [ANTIGRAVITY.md →](docs/ANTIGRAVITY.md) | +| **Claude Desktop** | Agent Panel → ... → MCP Servers → Edit configuration | [CLAUDE.md →](docs/CLAUDE.md) | > **Note:** Use absolute paths like `/Users/name/mt5-quant/mt5-quant` or `$(pwd)/mt5-quant`, not relative paths like `./mt5-quant`. @@ -60,7 +60,7 @@ The AI runs the full pipeline: compile → clean cache → backtest → extract | [WINDSURF.md](docs/WINDSURF.md) | Windsurf IDE setup | | [CURSOR.md](docs/CURSOR.md) | Cursor IDE setup | | [VSCODE.md](docs/VSCODE.md) | VS Code setup | -| [ANTIGRAVITY.md](docs/ANTIGRAVITY.md) | Antigravity IDE setup | +| [CLAUDE.md](docs/CLAUDE.md) | Claude Desktop setup | | [CONFIG.md](docs/CONFIG.md) | Configuration reference | | [TOOLS.md](docs/MCP_TOOLS.md) | All 87 tools documented | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design and internals | diff --git a/docs/ANTIGRAVITY.md b/docs/ANTIGRAVITY.md deleted file mode 100644 index 5c76bdc..0000000 --- a/docs/ANTIGRAVITY.md +++ /dev/null @@ -1,145 +0,0 @@ -# Antigravity MCP Integration Setup - -## Quick Setup - -### Option 1: Download Prebuilt Binary (Recommended) - -```bash -# macOS (Apple Silicon) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz -tar -xzf mt5-quant.tar.gz - -# Linux (x64) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz -tar -xzf mt5-quant.tar.gz -``` - -### Option 2: Build from Source - -```bash -cargo build --release -``` - -## Configure Antigravity - -### Step 1: Open MCP Manager - -1. Launch Antigravity -2. Look at the **right-side Agent Panel** -3. Click the **"..."** (More Options) menu at the top -4. Select **MCP Servers** - -### Step 2: Access Configuration - -1. Click **Manage MCP Servers** -2. Click **View raw config** or **Edit configuration** -3. This opens `mcp_config.json` - -### Step 3: Add mt5-quant Configuration - -Add to `mcp_config.json`: - -```json -{ - "mcpServers": { - "mt5-quant": { - "command": "/absolute/path/to/mt5-quant" - } - } -} -``` - -### Step 4: Reload and Verify - -1. Save the file -2. **Restart Antigravity** (or reload the window) -3. Open the Agent chat and type: `What tools do you have access to?` -4. The agent should list MT5 tools like `verify_setup`, `run_backtest`, etc. - -## Full Example Configuration - -```json -{ - "mcpServers": { - "mt5-quant": { - "command": "/Users/name/mt5-quant/target/release/mt5-quant" - }, - "github": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}" - } - } - } -} -``` - -## Environment Variables - -Antigravity supports `${VAR_NAME}` syntax for environment variable substitution: - -```json -{ - "mcpServers": { - "mt5-quant": { - "command": "/Users/name/mt5-quant/target/release/mt5-quant", - "env": { - "CUSTOM_VAR": "${env:MY_VAR}" - } - } - } -} -``` - -This keeps secrets out of the config file. - -## Verify Setup - -In Antigravity chat, type: - -``` -Run verify_setup -``` - -Expected output: -``` -Wine: /Applications/MetaTrader 5.app/.../wine64 -MT5 dir: ~/Library/Application Support/.../MetaTrader 5 -Display: gui -Arch: arch -x86_64 -``` - -## Troubleshooting - -### "Connection Refused" or "Tool not found" - -1. Double-check the server path in `mcp_config.json` -2. Ensure the binary has execute permissions: `chmod +x /path/to/mt5-quant` -3. Try completely restarting Antigravity -4. Check the server is listed in MCP manager - -### "Stdio Error" or JSON Parsing Error - -1. Verify the JSON syntax in `mcp_config.json` -2. Use a JSON validator if needed -3. Ensure no trailing commas - -### Agent Hallucinating Tool Parameters - -If the agent makes up incorrect parameters: -1. Check the tool is actually available: "List your available tools" -2. Restart the agent session -3. Be explicit in your requests - -## Configuration Location - -| Platform | Path | -|----------|------| -| All | Via UI: Agent Panel → ... → MCP Servers → Manage → Edit configuration | - -## Resources - -- [Antigravity Documentation](https://docs.antigravity.dev/) -- [MCP Server Reference](https://github.com/modelcontextprotocol/servers) -- [MT5-Quant Tools Reference](./MCP_TOOLS.md) diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 0000000..4cc4b3b --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1,138 @@ +# Claude Desktop MCP Integration Setup + +## Quick Setup + +### Option 1: Install via MCP Registry (Recommended) + +Search for `mt5-quant` in Claude Desktop's MCP manager, or add directly to your config. + +### Option 2: Download Prebuilt Binary + +```bash +# macOS (Apple Silicon) +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz +tar -xzf mt5-quant.tar.gz + +# Linux (x64) +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz +tar -xzf mt5-quant.tar.gz +``` + +### Option 3: Build from Source + +```bash +git clone https://github.com/masdevid/mt5-quant +cd mt5-quant +cargo build --release +``` + +## Configure Claude Desktop + +### Step 1: Open MCP Configuration + +Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). + +### Step 2: Add mt5-quant + +```json +{ + "mcpServers": { + "mt5-quant": { + "command": "/absolute/path/to/mt5-quant" + } + } +} +``` + +### Step 3: Reload and Verify + +1. Save the file +2. **Restart Claude Desktop** +3. In a new conversation, type: `What tools do you have access to?` +4. The agent should list MT5 tools like `verify_setup`, `run_backtest`, etc. + +## Full Example Configuration + +```json +{ + "mcpServers": { + "mt5-quant": { + "command": "/Users/name/mt5-quant/target/release/mt5-quant" + }, + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}" + } + } + } +} +``` + +## Environment Variables + +Claude Desktop supports `${env:VAR_NAME}` syntax for environment variable substitution: + +```json +{ + "mcpServers": { + "mt5-quant": { + "command": "/Users/name/mt5-quant/target/release/mt5-quant", + "env": { + "MT5_MCP_HOME": "${env:HOME}/.config/mt5-quant" + } + } + } +} +``` + +## Verify Setup + +In a Claude Desktop conversation, type: + +``` +Run verify_setup +``` + +Expected output: +``` +Wine: /Applications/MetaTrader 5.app/.../wine64 +MT5 dir: ~/Library/Application Support/.../MetaTrader 5 +Display: gui +Arch: arch -x86_64 +``` + +## Troubleshooting + +### "Tool not found" or server not appearing + +1. Double-check the absolute path in `claude_desktop_config.json` +2. Ensure the binary has execute permissions: `chmod +x /path/to/mt5-quant` +3. Restart Claude Desktop completely +4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (macOS) + +### JSON syntax errors + +1. Validate the JSON at [jsonlint.com](https://jsonlint.com) +2. Ensure no trailing commas +3. Use absolute paths (not `~` or relative paths) + +### Agent hallucinating tool parameters + +1. Verify the tool is available: "List your available MCP tools" +2. Start a new conversation +3. Be explicit: "Use the `run_backtest` tool with expert=MyEA" + +## Configuration Location + +| Platform | Path | +|----------|------| +| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | +| Windows | `%APPDATA%\Claude\claude_desktop_config.json` | + +## Resources + +- [Claude Desktop MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) +- [MCP Server Reference](https://github.com/modelcontextprotocol/servers) +- [MT5-Quant Tools Reference](./MCP_TOOLS.md) diff --git a/docs/CURSOR.md b/docs/CURSOR.md index 78c7004..9fbf03a 100644 --- a/docs/CURSOR.md +++ b/docs/CURSOR.md @@ -6,11 +6,11 @@ ```bash # macOS (Apple Silicon) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz tar -xzf mt5-quant.tar.gz # Linux (x64) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz tar -xzf mt5-quant.tar.gz ``` diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 0e86ecd..296a5fe 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -6,19 +6,19 @@ ```bash # macOS (Apple Silicon) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz tar -xzf mt5-quant.tar.gz # Linux (x64) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz tar -xzf mt5-quant.tar.gz ``` ### Option B: Build from Source ```bash -git clone https://github.com/masdevid/mt5-mcp -cd mt5-mcp +git clone https://github.com/masdevid/mt5-quant +cd mt5-quant bash scripts/build-rust.sh ``` @@ -137,7 +137,7 @@ Add to `.vscode/mcp.json` in your workspace: Or run `MCP: Add Server` from Command Palette. -### Antigravity +### Claude Desktop 1. Open Agent panel → Click "..." menu → MCP Servers 2. Click "Manage MCP Servers" @@ -153,7 +153,7 @@ Or run `MCP: Add Server` from Command Palette. } } ``` -5. Reload Antigravity to apply changes +5. Restart Claude Desktop to apply changes ## 5. Verify Setup diff --git a/docs/VSCODE.md b/docs/VSCODE.md index 79642b2..85296a0 100644 --- a/docs/VSCODE.md +++ b/docs/VSCODE.md @@ -6,11 +6,11 @@ ```bash # macOS (Apple Silicon) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz tar -xzf mt5-quant.tar.gz # Linux (x64) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz tar -xzf mt5-quant.tar.gz ``` diff --git a/docs/WINDSURF.md b/docs/WINDSURF.md index cf0777f..b1d614f 100644 --- a/docs/WINDSURF.md +++ b/docs/WINDSURF.md @@ -6,11 +6,11 @@ ```bash # macOS (Apple Silicon) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-macos-arm64.tar.gz tar -xzf mt5-quant.tar.gz # Linux (x64) -curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz +curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz tar -xzf mt5-quant.tar.gz ```