iWind AIFin Connector

English | 中文

A self-hosted, read-only bridge between Wind financial-data MCP services and AI agents such as ChatGPT Work, Grok Web, Codex, and other MCP-capable clients.

This repository is not a hosted data service and does not include Wind access. You bring your own Wind entitlement and API keys, deploy the gateway to your own Cloudflare account, and connect your agent to the resulting OAuth MCP endpoint.

Why this project exists

Wind exposes useful financial data through multiple MCP services. Configuring every service and every API key separately in every agent is difficult to maintain, especially when a key reaches its quota.

iWind AIFin Connector provides one stable, OAuth-protected MCP endpoint and one runtime-neutral Skill:

ChatGPT Work / Grok Web / local agent
              │
              ├── Skill: intent routing, data-quality checks, fail-closed rules
              │
              └── OAuth MCP connection
                         │
                         ▼
               Cloudflare Worker gateway
               ├── OAuth and access control
               ├── 31-tool read-only manifest
               ├── serial ordered key pool (active primary ring: five slots)
               └── sanitized operations notices
                         │
                         ▼
                  Six Wind MCP services

The Cloudflare Plugin described below is a setup and maintenance assistant. It can help an agent create or inspect Cloudflare resources, but it is not part of the production Wind-query data path.

Related MCP server: Wind MCP

What it can do

Integrated Wind domains

The gateway does not expose trading or write actions.

How key rotation works

The stable catalog contains key-01 through key-05. The active primary layout ring-primary-v2 orders a new pool key-05 → key-04 → key-03 → key-02 → key-01; its KeyPool persists a cursor that identifies the current slot. The prior key-01 → key-02 pool remains a legacy generation for rollback compatibility and OAuth replay, not for new business calls.

This repository's primary-layout revision is awaiting merge. The currently deployed Cloudflare production environment remains on the legacy two-slot generation until a separately approved cutover; this documentation does not claim that cutover is complete.

1. A new primary v2 pool starts on key-05; ordinary success keeps the cursor there, so requests do not alternate between keys.

2. Exact daily-quota, balance, authentication, or operator-disable events move the cursor to the next declared slot: key-05 → key-04 → key-03 → key-02 → key-01 → key-05. Balance, authentication, and manual-disable states remain unavailable until explicitly restored.

3. Each logical invocation can acquire every eligible slot at most once. If that bounded pass is exhausted, the call stops; a later independent invocation starts a new bounded pass from the persisted cursor.

4. A trusted future reset_at keeps a daily-exhausted slot unavailable until its reset. When no trusted reset is supplied, the slot remains eligible for a later wrap-around probe instead of requiring a guessed reset time or manual restore.

5. QPS cooldown, concurrency errors, timeouts, network failures, oversized responses, upstream 5xx responses, and unknown errors do not move the cursor or burn through the pool.

6. The agent receives a sanitized notice when rotation occurred, failed, or the pool is unavailable. Key values and raw infrastructure details are never included.

This is event-driven ring failover, not per-request round-robin load balancing and not a way to bypass Wind account or contract limits. Only use keys you are legally allowed to pool under your Wind agreement.

gateway/src/key-pool/slots.ts is the single non-Secret catalog, layout, and generation declaration. Slot identity and binding are stable; priority is runtime topology derived from the persisted layout, not identity or global number sorting. An ordinary future expansion appends only new catalog bindings, then defines an approved successor block that is inserted immediately before the actual persisted cursor and becomes the new cursor; it preserves the old effective ring order. Replacement updates the same binding and restores the same slot. Reorder, deletion, rename, or any layout that is not a cursor-relative successor block requires a new generation and blue-green cutover. The release never discovers undeclared Secrets automatically. The MCP endpoint, 31-tool manifest, OAuth flow, administration URL shape, and Skill package remain unchanged.

An ordinary future append is deliberately two-stage: deploy an expand candidate that recognizes the new catalog entry, Secret binding, and candidate layout while keeping the active layout unchanged; then deploy an activate candidate that switches to that prefix-compatible layout. After activation, rollback may target only the expand candidate (or a newer revision) that recognizes the activated layout. See operations for the complete runbook.

Prerequisites

You need:

• A Wind AIFin account or entitlement that can use the integrated MCP services.

• Five Wind API keys for the repository's active primary layout. The keys must never be committed to this repository.

• A Cloudflare account with Workers, KV, Durable Objects, Cron Triggers, and an approved Access/OIDC application.

• Git, npm, and Node.js >=24.13.1.

• An MCP-capable agent or client for using the deployed service.

Cloudflare, Wind, identity-provider, and AI-platform charges or limits are controlled by those services and are not included with this repository.

Recommended: install the Cloudflare Plugin first

If you want ChatGPT or Codex to help provision and maintain the Cloudflare resources, install the official Cloudflare Plugin before starting deployment:

1. Open the OpenAI Plugin directory, search for Cloudflare, install it, and complete Cloudflare OAuth.

2. Review the requested Cloudflare permissions before approving them.

3. Ask the agent to read this repository's installation runbook and security boundary before it changes any resource.

The reusable Cloudflare Skills are also published in the Apache-2.0 licensed cloudflare/skills repository:

npx skills add https://github.com/cloudflare/skills

The OpenAI-distributed package structure is visible in openai/plugins › cloudflare. These open repositories contain the Plugin/Skill instructions and connection packaging. The hosted Cloudflare API MCP service they connect to is a separate remote service; do not assume its server implementation is included in either repository.

Installing this Plugin is recommended for agent-guided setup, but the deployed iWind gateway does not depend on the Plugin at runtime. A qualified operator can follow the Wrangler runbook directly.

Quick start

1. Clone the repository

git clone https://github.com/Rainnystone/iwind-connector.git
cd iwind-connector
npm ci

2. Prepare private Wind keys

Create a private env file outside the repository. This project's local convention is ../.secrets/iwind.keys.env:

WIND_API_KEY_01=replace-with-your-first-key
WIND_API_KEY_02=replace-with-your-second-key
WIND_API_KEY_03=replace-with-your-third-key
WIND_API_KEY_04=replace-with-your-fourth-key
WIND_API_KEY_05=replace-with-your-fifth-key

Restrict the file to its owner. Do not paste real values into source files, Markdown, chat messages, screenshots, command arguments, or deployment JSON.

Cloudflare deployment also requires the Secret binding names listed in gateway/wrangler.jsonc under secrets.required. Supply their values through approved protected input; never replace the checked-in safe sentinels with production values.

For an approved deployment, use the complete owner-only Cloudflare Secret file described in installation: an existing Worker receives an un-deployed versions upload candidate, exact versions view <candidate> --config dist/wrangler.deploy.jsonc --json names-only inspection, then an explicit exact @100% deployment with that same rendered config; first creation uses one complete deploy --secrets-file. Do not use per-binding secret put, because it immediately deploys a version.

3. Verify the checkout

Run from the repository root:

npm test
npm run typecheck
npm run lint
npm run contract:verify
npm run build

npm run build is a Wrangler dry run; it does not deploy. It may clear the shared dist/ directory, so always package the Skill after the build:

npm run skill:package
npm run secret:scan -- --secrets-file '../.secrets/iwind.keys.env'

The generated archive is:

dist/iwind-aifin-connector-skill.zip

4. Deploy the gateway to your Cloudflare account

Follow docs/installation.md exactly. It explains how to:

• create or select the OAuth KV namespace;

• render a deploy-only Wrangler config without changing source sentinels;

• supply all required Secrets through protected input;

• review the Worker, Durable Object, KV, cron, origin, and OAuth configuration;

• perform a dry run before the separately approved deployment;

• verify OAuth, 31 read-only tools, one representative query, and key-pool status.

If an agent is helping, a safe starter request is:

Read README.md, docs/installation.md, and docs/security.md. Explain the Cloudflare resources and Secret bindings I need. Do not create, modify, or deploy anything until you show me the exact plan and I approve it.

Deployment mutates external infrastructure. Review the target Cloudflare account, resource names, OAuth policy, public origin, and estimated service costs before approving it.

5. Connect an agent

Use the same Skill archive and the same deployed OAuth MCP endpoint everywhere:

• ChatGPT Work: register the deployed /mcp URL as an OAuth custom Plugin, then upload the Skill zip as a separate item.

• Grok Web: register the OAuth MCP connector and install the same Skill archive according to the current product UI.

• Local clients: install the Skill archive and adapt the provided MCP configuration example.

The Skill does not install or authenticate the MCP connection, and the MCP connection does not automatically install the Skill. Cloud runtimes require both steps.

6. Run a read-only smoke test

Start with a known canonical Wind code and a simple snapshot request. Confirm that:

• the client uses the iWind MCP rather than Web Search;

• the selected tool matches the requested data type;

• calls are serial;

• the response preserves dates, units, nulls, and coverage;

• ordinary success has no operations warning;

• no credential or raw diagnostic appears in the answer.

For a company name or uncertain code, the Skill should first search the identity, validate the company, canonical Wind code, and market, and only then call a property or price tool.

Operations and maintenance

• Operations: inspect the pool, replace/add/disable/restore a key, or refresh the Wind schema snapshot.

• Troubleshooting: interpret stable OAuth, gateway, key-pool, and Wind error codes.

• Security: Secret handling, logging allowlist, package scanning, and release gates.

• Acceptance checklist: the full verified release boundary and remaining platform-specific checks.

Do not change key-pool size, rotation semantics, OAuth policy, public endpoints, tool schemas, or read-only scope as an operations shortcut. Those are architecture changes and require implementation and review.

Repository layout

skill/                 Runtime-neutral Agent Skill, references, and evals
gateway/               Cloudflare Worker OAuth MCP gateway
adapters/              ChatGPT Work, Grok Web, and local installation notes
scripts/               Packaging, verification, Secret scanning, and deploy rendering
docs/                  Installation, operations, security, troubleshooting, and acceptance
dist/                  Generated and ignored release artifacts

The Skill package contains only SKILL.md, references/*.md, and evals/*.json under a fixed iwind-aifin-connector/ root. It contains no endpoint, Wind key, OAuth credential, gateway code, platform metadata, or copied tool schema.

Verification status

The repository has automated unit, integration, MCP/OAuth, five-slot cursor-relative rotation, serialization, packaging, Secret-scan, and dry-run build coverage. Historical production evidence must not be treated as evidence that this v0.6 ring-primary-v2 layout has been deployed; Cloudflare rollout requires separate approval.

ChatGPT Work custom-Plugin registration, OAuth, tool discovery, and a representative query have been verified. Final Skill upload, automatic Skill invocation, and scheduled-task behavior remain account-level acceptance steps. The Grok Web adapter is provided but has not yet been verified in a real Grok account. See the acceptance checklist for the current boundary.

Repository licensing and data access

The delivery repository's code and documentation are Secret-free and designed to be auditable. That does not make any deployed gateway a public data service, and it does not include, grant, or authorize redistribution of Wind data access. Every operator must use their own Cloudflare account, identity configuration, Wind entitlement, and private API keys.

This repository currently has no LICENSE file. Source availability or access alone does not grant a general open-source reuse license, so the project should not be described as licensed open source unless and until a license is added. Choose and add an appropriate license before encouraging redistribution or third-party contributions.

If you fork, deploy, or redistribute this project:

• never commit credentials, OAuth artifacts, account identifiers, private deployment records, temporary callback URLs, or business responses;

• run the full verification, deterministic packaging, and exact-value Secret scan against your own private key file;

• review your Wind agreement before redistributing generated contract information or offering a service to other people;

• keep the gateway read-only unless a different security boundary has been deliberately designed, authorized, implemented, and reviewed.

Wind and iWind product names belong to their respective owner. This is an independent integration project and is not affiliated with or endorsed by Wind. It does not provide, resell, or grant access to Wind data.