# Stock Compass setup guide for AI assistants The user asked you to set them up with Stock Compass. This guide is written for any AI app or agent. Follow it in order. Do the steps you can do yourself, and for the rest give the user one clear step at a time and wait for them. **What Stock Compass is**: - It is a personal decision and review tool for Hong Kong, US and China A-share stocks (https://stock-compass.app). - The user writes their own trading rules as strategies. Every trading day it scans their watchlist with those rules, records each signal, and keeps their trades and trade journal. - It is not a broker and gives no tips. - Once connected, you can read the user's watchlist, holdings, signals, trades and price alerts. If they allow it, you can also record trades, change stops and targets, and set price alerts. - Connecting needs a Stock Compass **Pro** account. New accounts get a free 14-day Pro trial with no card. ## Ground rules - **Sign-in happens in the user's browser.** - Never ask for their password. - Never ask them to paste an API key into the conversation; a key belongs in the app's own settings. - Never ask for their email unless they offer it. - **Change nothing during setup without asking.** Writes change the user's real records. Before any write, state the exact change and wait for a yes. - **No advice.** Signals are the user's own rules firing. Do not recommend buying, selling or holding. - **Records only.** Recording a trade writes it into Stock Compass. It never places an order with a broker. - **Language.** Reply in the user's language. The website is in English and Chinese. Labels below are written as the English site shows them, with the Chinese site's label in brackets; name the one the user's site shows. ## Step 1. Learn Stock Compass Read the skill now. It explains every feature, the tools, and the rules for using them: - https://raw.githubusercontent.com/Stock-Compass/stock-compass-plugin/main/skills/stock-compass/SKILL.md - https://raw.githubusercontent.com/Stock-Compass/stock-compass-plugin/main/skills/stock-compass/references/product.md - https://raw.githubusercontent.com/Stock-Compass/stock-compass-plugin/main/skills/stock-compass/references/strategies.md - https://raw.githubusercontent.com/Stock-Compass/stock-compass-plugin/main/skills/stock-compass/references/api.md Read SKILL.md first. Read a reference file only when a question needs it. ## Step 2. Make sure the user has an account Ask whether they already have a Stock Compass account. - **No account**: send them to https://stock-compass.app/login?mode=signup&intent=trial. - They sign up with email and password, or with Google, and confirm their email. - The Pro trial starts by itself when they confirm on the same device. If they confirm on another device, the site asks "Start your Pro trial?" (开始 Pro 试用？); they press **Start trial** (开始试用). - No card is needed, and the trial does not turn into a charge. - **Account on the free plan**: they can start the free trial on the approval page in Step 4, or at https://stock-compass.app/en/pricing. One trial per account. - **Pro already**: go on. Wait until they say they are signed in before Step 3. ## Step 3. Connect the user's app Work out which app you are running in. If you are not sure, ask. The MCP server is: `https://stock-compass.app/api/mcp` It uses Streamable HTTP and signs in with OAuth. ### Claude Code (you can run commands) Ask the user before running anything, then run: ```bash claude plugin marketplace add Stock-Compass/stock-compass-plugin claude plugin install stock-compass@stock-compass ``` This installs the Stock Compass connector and this skill. Then ask the user to: 1. type `/reload-plugins`; 2. type `/mcp` and pick `plugin:stock-compass:stock-compass`; 3. sign in and approve in the browser that opens. If the `claude` command is not available to you, give the user the two commands to run in their own terminal instead. ### Claude (claude.ai, the desktop app, Cowork) The user does these steps: 1. **Customize → Plugins → Add → Add marketplace**, enter `Stock-Compass/stock-compass-plugin`, then install **Stock Compass**. 2. Open the plugin's **Connectors** tab and press **Connect**. 3. Sign in and approve (Step 4). Without the plugin, they can add `https://stock-compass.app/api/mcp` as a custom connector in Settings → Connectors. ### ChatGPT The user does these steps: 1. Open https://chatgpt.com/plugins, press **+**, then **Add custom MCP server**. 2. Name: `Stock Compass`. URL: `https://stock-compass.app/api/mcp`. 3. Authentication: **OAuth**. Leave any client ID and secret fields empty; Stock Compass registers ChatGPT by itself. 4. Accept the risk notice ("I understand and want to continue") and press **Create as a plugin**. 5. Sign in and approve (Step 4). 6. Start a new chat, type `@` and pick Stock Compass. If "Add custom MCP server" is not there, developer mode may need to be switched on in ChatGPT's settings, or a workspace admin may need to allow it. ### Any other MCP client (Cursor, Codex, Gemini CLI, VS Code and others) Add a remote MCP server with the address above, transport Streamable HTTP, authentication OAuth. - If you can edit the client's configuration yourself, show the user the exact change and ask first. - If the client cannot do OAuth, it can use a personal API key instead: 1. The user creates one in Stock Compass under Settings → AI apps & API (设置 → AI 应用与 API). 2. They put it in the client's configuration as the header `Authorization: Bearer sc_…`. - If the client loads Agent Skills (`SKILL.md`), save the four skill files above into its skills folder as `stock-compass/SKILL.md` and `stock-compass/references/…`. ### No MCP support The user can still use Stock Compass on the website, and you can explain it from the skill. Scripts can use the REST API with an API key; see references/api.md. Menu names in other companies' apps can change. If a step does not match what the user sees, look for that app's setting for adding a remote MCP server or connector. ## Step 4. The approval page The connection opens Stock Compass in the browser. If the user is not signed in, they sign in or sign up there first. The page shows: - which app wants to connect; - where the answer will be sent (for example claude.ai or chatgpt.com, or localhost for a program on their own computer). Approval is read only by default: the button reads **Allow reading** (允许读取). To let you make changes, the user ticks **Make changes** (修改) first, and the button becomes **Allow reading and changes** (允许读取和修改). If the account is not on Pro: - if it can still start the trial, the page offers **Start the 14-day free trial and continue** (免费试用 14 天并继续); - otherwise it links to the pricing page. If something times out after a sign-up or an email confirmation, press Connect in the app again. ## Step 5. Check that it works Call `get_watchlist`. Then tell the user, briefly, what you found: how many stocks, in which markets, and how many are held. If the call fails, see Troubleshooting below. ## Step 6. First steps **What a new account starts with**: - An empty watchlist. - A default strategy, "Balanced (Default)", active in each market. They can review it on the Strategies page (策略管理), or you can help them write their own rules (references/strategies.md). There is no tool for changing strategies: you give them JSON to paste with **Paste JSON to import** (粘贴 JSON 导入) on the Strategies page. **Help them through these steps, asking before each write**: 1. **Add the stocks they follow** with `add_to_watchlist`. Ask for the market (hk, us, cn) and ticker. 2. **Record what they already hold** with `record_trade`: type buy, price, quantity and date. Ask whether they want a stop and a target on each holding; a stop set at entry is what the execution record measures. 3. **Explain when signals come**: - The scan runs on weekdays: HK and A-shares at 09:00, 13:00, 14:00 and 15:00 Hong Kong time; US at 09:00, 12:00 and 15:00 New York time. - Buy and add signals are confirmed after the daily close. - Signals appear on the website's Today's Signals (今日信号) page, and you can read them with `get_signals`. 4. **Optional**: - email alerts for signals (Settings → Notifications, Pro); - price alerts; - the weekly review email every Monday, which is on by default. Do these one at a time, at the user's pace. ## Troubleshooting - **Not connected, 401, or "invalid token"**: connect again from the app. An approval can be withdrawn at any time in Settings → AI apps & API. - **"This connection may only read"**: the user approved read only. They disconnect the app in Settings → AI apps & API, connect again, and tick changes. - **"part of Stock Compass Pro"**: the account is not on Pro. Start the trial (Step 2) or see the pricing page. - **"not on the watchlist"**: add the stock first, after asking. - **Too many requests (429)**: the limit is 60 requests a minute. Wait a minute. - **ChatGPT shows old tools**: open the connection at chatgpt.com/plugins and press Refresh. ## Links - Website: https://stock-compass.app (English: https://stock-compass.app/en, Chinese: https://stock-compass.app/zh) - Sign up with a free Pro trial: https://stock-compass.app/login?mode=signup&intent=trial - About connecting AI apps: https://stock-compass.app/en/ai (Chinese: https://stock-compass.app/zh/ai) - Plugin and skill: https://github.com/Stock-Compass/stock-compass-plugin - Pricing: https://stock-compass.app/en/pricing - Privacy: https://stock-compass.app/en/privacy - Support: support@stock-compass.app