# KLinePic MCP Server and Agent API Examples

[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) | [한국어](README.ko-KR.md)

[![CI](https://github.com/sher1096/klinepic-agent-api-examples/actions/workflows/ci.yml/badge.svg)](https://github.com/sher1096/klinepic-agent-api-examples/actions/workflows/ci.yml)
[![GitHub stars](https://img.shields.io/github/stars/sher1096/klinepic-agent-api-examples?style=flat)](https://github.com/sher1096/klinepic-agent-api-examples/stargazers)
[![Glama score](https://glama.ai/mcp/servers/sher1096/klinepic-agent-api-examples/badges/score.svg)](https://glama.ai/mcp/servers/sher1096/klinepic-agent-api-examples)
[![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-sher1096-klinepic-agent-api-examples-e5c2d581/badge.svg)](https://tensorblock.co/mcp/servers/github-sher1096-klinepic-agent-api-examples-e5c2d581)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](https://nodejs.org/)

Turn broker or exchange fills into annotated candlestick review-chart PNGs. AI agents can discover capabilities, validate a request without spending chart quota, and render the finished chart through three MCP tools.

Run it as an Agent Skill, from source, with the one-click MCPB bundle, or in Docker; the repository also includes OpenAPI examples.

KLinePic is for post-trade review and visualization. It does not provide trading signals, price predictions, investment advice, or order execution.

## Example output

[![Example KLinePic post-trade candlestick review chart using sample SOLUSDT data](https://klinepic.com/use-case-previews/agent-sol-deep-en.png)](https://klinepic.com/guides/trade-review-chart-api/?utm_source=github&utm_medium=referral&utm_campaign=geo202607)

_Sample-data preview. It is not a trading signal, forecast, or investment recommendation._

## What is included

| Tool | What it does | Quota impact |
| --- | --- | --- |
| `klinepic_get_capabilities` | Checks API-key permissions, plan limits, remaining quota, and supported endpoints. | None |
| `klinepic_preflight_review_chart` | Validates fills, K-line data, scopes, and estimated cost before rendering. | None |
| `klinepic_create_review_chart` | Returns an annotated candlestick PNG as native MCP image content. | Uses one chart render |

The repository also includes:

- A reusable Agent Skill for Codex, Claude Code, and other compatible agents.
- A working JavaScript stdio MCP server.
- A small Agent API client used by the MCP tools.
- Broker, Binance, US-stock, futures, and MetaTrader sample data.
- A complete review-chart request and a no-charge preflight example.
- Docker support, an OpenAPI mirror, and machine-readable discovery files.

## Verified functionality

Local installation was last verified on **2026-07-14**. Live API capabilities and preflight were last verified on **2026-07-13**:

| Check | Result | What was proved |
| --- | --- | --- |
| API adapter tests | PASS — 4/4 | Bearer authentication, forced review-chart mode, PNG-to-base64 conversion, and structured error handling. |
| Agent Skill validation and discovery | PASS — 1 skill | The official skill validator accepted the package, and the current `skills` CLI found `klinepic-trade-review` from a clean repository scan. |
| Real MCP stdio handshake | PASS — 3 tools | A real MCP client completed initialization and discovered all three tool schemas. |
| Fresh Cline-compatible install | PASS — 3 tools | The Windows `cmd /c npx` configuration launched the GitHub package from an empty temporary directory and completed MCP initialization plus tool discovery. |
| One-click MCPB bundle | PASS — 3 tools | The official MCPB 0.3 validator accepted the manifest; the packed bundle included runtime dependencies and completed a real stdio handshake. |
| Live production capabilities | PASS | The MCP server called the production capability endpoint with a scoped Agent API key. |
| Live production preflight | PASS | The sample request passed production validation without rendering a chart or consuming chart quota. |
| Container build | PASS in CI | GitHub Actions builds the Docker image from a clean checkout. |

Reproduce the local checks:

```bash
npm ci
npm test
npm run test:mcpb
```

Run the live, no-charge check with your own key:

```bash
KLINE_AGENT_API_KEY=kline_agent_xxx npm run test:production-preflight
```

The live check calls capabilities and preflight only. It does not call the paid render tool.

## Quick start

Requirements:

- Node.js 20 or newer.
- A KLinePic Agent API key. [Create one from the account page](https://klinepic.com/account?utm_source=github&utm_medium=referral&utm_campaign=geo202607); the free tier does not require a sales conversation.

Install the reviewed post-trade workflow as an [Agent Skill](skills/klinepic-trade-review/SKILL.md):

```bash
npx skills add sher1096/klinepic-agent-api-examples --skill klinepic-trade-review
```

The skill tells a compatible agent to inspect completed fills, run the free preflight, ask before consuming render quota, and avoid signals, predictions, advice, or order execution.

One-click install for MCPB-compatible desktop clients:

[Download `klinepic-mcp-server-0.1.0.mcpb`](https://github.com/sher1096/klinepic-agent-api-examples/releases/latest/download/klinepic-mcp-server-0.1.0.mcpb), open it in the desktop client, and enter the Agent API key when prompted. The key field is marked sensitive. The API origin defaults to `https://klinepic.com`; change it only to a trusted HTTPS endpoint because the key and full trade payload are sent there.

Run directly from GitHub:

```bash
KLINE_AGENT_API_KEY=kline_agent_xxx \
  npx -y github:sher1096/klinepic-agent-api-examples#c48f3dc12a21834a2af165c223230f0cf9500fef
```

Or clone the repository:

```bash
git clone https://github.com/sher1096/klinepic-agent-api-examples.git
cd klinepic-agent-api-examples
npm ci
KLINE_AGENT_API_KEY=kline_agent_xxx npm start
```

## MCP client configuration

Most macOS and Linux clients can run the GitHub package directly:

```json
{
  "mcpServers": {
    "klinepic": {
      "command": "npx",
      "args": [
        "-y",
        "github:sher1096/klinepic-agent-api-examples#c48f3dc12a21834a2af165c223230f0cf9500fef"
      ],
      "env": {
        "KLINE_AGENT_API_KEY": "kline_agent_xxx"
      }
    }
  }
}
```

Some Windows clients need `cmd.exe` to resolve `npx.cmd`:

```json
{
  "mcpServers": {
    "klinepic": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "github:sher1096/klinepic-agent-api-examples#c48f3dc12a21834a2af165c223230f0cf9500fef"
      ],
      "env": {
        "KLINE_AGENT_API_KEY": "kline_agent_xxx"
      }
    }
  }
}
```

Keep the key in the client environment or secret store. Do not commit it.

## Docker

Run the published image:

```bash
docker run --rm -i \
  -e KLINE_AGENT_API_KEY=kline_agent_xxx \
  ghcr.io/sher1096/klinepic-mcp-server:0.1.0
```

Or build it locally:

```bash
docker build -t klinepic-mcp .
docker run --rm -i \
  -e KLINE_AGENT_API_KEY=kline_agent_xxx \
  klinepic-mcp
```

The container can start without a key so a registry can inspect its tool schemas. API calls still require a valid key.

## Recommended agent flow

1. Call `klinepic_get_capabilities`.
2. Build a request from the user's fills and K-line data.
3. Call `klinepic_preflight_review_chart`.
4. Fix any validation or permission error.
5. Ask for confirmation before a quota-consuming render.
6. Call `klinepic_create_review_chart` and return the PNG.

Preflight first: it catches malformed CSV, unsupported sources, missing scopes, IP restrictions, plan state, and quota limits without rendering.

## Sample data

| File | Use case |
| --- | --- |
| [`review-chart-request.json`](sample-data/review-chart-request.json) | Complete request for preflight or rendering |
| [`broker-trades-template.csv`](sample-data/broker-trades-template.csv) | Generic broker exports |
| [`binance-trade-history-template.csv`](sample-data/binance-trade-history-template.csv) | Binance trade history |
| [`us-stock-trading-journal-template.csv`](sample-data/us-stock-trading-journal-template.csv) | US-stock journals |
| [`futures-trade-review-template.csv`](sample-data/futures-trade-review-template.csv) | Futures reviews |
| [`metatrader-trade-history-template.csv`](sample-data/metatrader-trade-history-template.csv) | MetaTrader 4/5 history |

Run the standalone no-charge example:

```bash
KLINE_AGENT_API_KEY=kline_agent_xxx node examples/preflight.mjs
```

## Troubleshooting

- **`KLINE_AGENT_API_KEY is required`** — create a key and pass it through the MCP client's environment.
- **HTTP 401** — the key is invalid or revoked.
- **HTTP 402** — the account or key quota is exhausted; capabilities shows the relevant limit.
- **HTTP 403** — the key lacks the required scope or its IP allowlist blocks the caller.
- **HTTP 422** — the request data is invalid; run preflight and inspect the structured details.
- **Windows cannot find `npx`** — use the `cmd /c npx` configuration above.

## Documentation and discovery

- [Cline installation guide](llms-install.md)
- [Standalone field guide](https://sher1096.github.io/klinepic-agent-api-examples/)
- [Complete AI/GEO context bundle](https://sher1096.github.io/klinepic-agent-api-examples/llms-full.txt)
- [Human-readable Agent API guide](https://klinepic.com/guides/trade-review-chart-api/?utm_source=github&utm_medium=referral&utm_campaign=geo202607)
- [OpenAPI contract](https://klinepic.com/api/agents/openapi.json)
- [GitHub Pages OpenAPI mirror](https://sher1096.github.io/klinepic-agent-api-examples/openapi.json)
- [Copy-paste quickstart](guides/klinepic-agent-api-quickstart.md)
- [Accepted Agent Skill installation and guardrails Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/12)
- [Accepted one-click MCPB install and checksum Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/7)
- [Accepted official MCP Registry and OCI Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/4)
- [Claimed Glama listing and quality score](https://glama.ai/mcp/servers/sher1096/klinepic-agent-api-examples)
- [MCP Repository directory listing](https://mcprepository.com/sher1096/klinepic-agent-api-examples)
- [HeyClaude MCP directory listing](https://heyclau.de/entry/mcp/klinepic-mcp-server)
- [LobeHub MCP Marketplace listing](https://lobehub.com/mcp/sher1096-klinepic-agent-api-examples)
- [TensorBlock MCP Index profile — maintained by `@sher1096`; verification: self-reported](https://tensorblock.co/mcp/servers/github-sher1096-klinepic-agent-api-examples-e5c2d581)
- [Chinese community walkthrough: turn broker fills into an auditable review chart](https://zhuanlan.zhihu.com/p/2060477326857708905)
- [Accepted MCP installation Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/3)
- [Accepted broker-fill workflow Q&A](https://github.com/sher1096/klinepic-agent-api-examples/discussions/1)
- [中文 A 股交割单问答](https://github.com/sher1096/klinepic-agent-api-examples/discussions/2)

## Security and scope

- Report suspected vulnerabilities through the [private security-reporting form](SECURITY.md), not a public issue.
- API keys are sent only to `https://klinepic.com` unless `KLINEPIC_BASE_URL` is explicitly overridden.
- The server does not store keys, trade records, or generated images locally.
- Use a dedicated key with the smallest useful scopes and limits.
- Review data-handling requirements before sending real trading records.

## License

The MCP adapter and examples in this repository are available under the [MIT License](LICENSE). The hosted KLinePic API is a separate service governed by its published terms and privacy policy.