<p align="center">
  <img src="docs/banner.png" alt="Junto banner" width="100%">
</p>

# Junto

**An investment committee for your AI agent.**

Junto is a local first MCP server and command line tool for equity research. It gives Claude Code, Codex, Cursor, and OpenCode a repeatable research workflow with cited data, deterministic committee views, reproducible backtests, and an auditable track record.

Junto does not execute trades. It is not financial advice.

## Why Junto

AI agents are good at reading and summarizing. They are less reliable when a question needs a consistent process. Junto turns an open ended request such as "should I look at NVDA" into a run you can inspect.

- Five independent views. Business quality, valuation, growth, risk, and technicals each score the same evidence with fixed rules.
- Citations on every run. Quotes, price history, fundamentals, and news keep their provider links.
- Reproducible backtests. Signals use the close and execute at the next open. Costs and slippage apply on both sides.
- An auditable record. Committee calls can be stored locally and marked to market after the stated horizon.
- Local first state. Reports, cache, and the track record stay in `~/.junto` unless you override `JUNTO_HOME`.
- No API keys. Junto uses public market data and news endpoints.
- No trade execution. Junto is research software only.

## Quick start

Run the offline demo with no account, no API key, and no network access.

```sh
npx -y junto@latest demo NVDA --offline
```

Open the HTML report printed by the command. The demo uses a bundled dataset, so the market inputs stay fixed and no network requests are made.

Run a live committee for a US ticker or a China A share.

```sh
npx -y junto@latest committee AAPL --open
npx -y junto@latest committee 600519.SS --open
```

The `--open` flag opens the HTML report in your default browser.

## Install

Junto runs on Node 20 or later and on Bun 1.0 or later.

```sh
npm install -g junto
junto --version
```

With Bun.

```sh
bun add -g junto
bunx junto serve
```

You can also run Junto without a global install.

```sh
npx -y junto@latest serve
```

## Connect your agent

Junto exposes the same five tools to every MCP client.

Claude Code.

```sh
claude mcp add --transport stdio junto -- npx -y junto serve
```

Codex.

```sh
codex mcp add junto -- npx -y junto serve
```

Cursor project config at `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "junto": {
      "command": "npx",
      "args": ["-y", "junto", "serve"]
    }
  }
}
```

OpenCode V2 project config at `opencode.json`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "junto": {
        "type": "local",
        "command": ["npx", "-y", "junto", "serve"],
        "enabled": true
      }
    }
  }
}
```

See [docs/mcp-clients.md](docs/mcp-clients.md) for project level configs, local build paths, and troubleshooting.

## CLI

| Command | What it does |
| --- | --- |
| `junto serve` | Start the MCP server over stdio |
| `junto demo [symbol]` | Run a demo and write a report |
| `junto research <symbol>` | Print a cited research snapshot |
| `junto committee <symbol>` | Run the committee and write a memo |
| `junto backtest <symbol>` | Run a reproducible backtest |
| `junto track` | Evaluate the local track record |
| `junto doctor` | Check the local setup and data sources |

Use `junto help` for all flags and examples.

## MCP tools

| Tool | What it returns | Local side effects |
| --- | --- | --- |
| `research_asset` | Quote, fundamentals, technicals, news, citations, and limitations | Reads data only |
| `run_committee` | Five persona views, consensus, memo text, and report paths | Writes reports and appends to the track record by default |
| `run_backtest` | Metrics, trades, equity curve, and assumptions | Reads data only |
| `get_track_record` | Prior calls marked to market with hit, miss, and pending status | Reads data only |
| `get_memo` | A saved Markdown or HTML report by run id | Reads data only |

All tools return JSON text content. `run_committee` also returns the full Markdown memo.

## Reports and track record

Junto writes two report formats for each saved run.

```text
~/.junto/reports/{runId}.md
~/.junto/reports/{runId}.html
```

The local track record is a JSONL file.

```text
~/.junto/track-record.jsonl
```

Set `JUNTO_HOME` to move all state to another directory. The offline demo writes reports but does not append to the track record.

## How it works

Junto builds one research snapshot per asset. The snapshot contains a quote, five years of daily adjusted prices, fundamentals when available, technical indicators, and recent news.

Five personas score the snapshot with fixed rules. Business quality covers margins, returns, and growth. Valuation covers earnings and book multiples. Growth covers reported growth and price momentum. Risk covers volatility, drawdown, and leverage. Technicals covers trend, RSI, MACD, and short term momentum.

The consensus is a weighted average. Business quality has a weight of 25 percent. Valuation, growth, and risk each have a weight of 20 percent. Technicals has a weight of 15 percent. Confidence falls when the personas disagree or when coverage is incomplete.

The default report uses a 50 and 200 day moving average cross when enough history is available. Otherwise it uses buy and hold. Signals use the close and execute at the next open. The report lists the assumptions and limitations.

News is context only and never changes the score. Junto does not use a language model to choose a stance. The same inputs and rules produce the same verdict.

Read [docs/methodology.md](docs/methodology.md) for the full scoring and backtest specification.

## Data sources

| Provider | Used for | Notes |
| --- | --- | --- |
| Eastmoney | Daily price history and fallback quotes | Primary history source for US and China A shares |
| Tencent | Live quotes, price to earnings, price to book, and market cap | Responses use GBK encoding |
| Nasdaq | US company profile and annual fundamentals | Uses browser style request headers |
| Yahoo Finance RSS | Recent news | Public RSS feed |
| Google News RSS | News when Yahoo has few items | Public RSS feed |

Providers can be rate limited or unavailable. Junto records missing inputs as limitations instead of inventing data. Read [docs/data-sources.md](docs/data-sources.md) for provider behavior and symbol formats.

## Privacy and local state

Junto has no telemetry and no account system. A live run contacts the data providers listed above. The offline demo reads only the bundled fixtures. The cache is safe to delete.

| Variable | Default | Purpose |
| --- | --- | --- |
| `JUNTO_HOME` | `~/.junto` | Cache, reports, and track record location |
| `JUNTO_LOG` | `error` | Log level for `silent`, `error`, `info`, or `debug` |
| `JUNTO_TIMEOUT_MS` | `20000` | Network request timeout |
| `JUNTO_HORIZON_DAYS` | `90` | Default committee horizon |

There are no API keys to configure.

## Sample report

Open the [HTML sample](docs/sample-report.html) or read the [Markdown sample](docs/sample-report.md). Both files were generated from the bundled NVDA demo dataset.

## Development

```sh
git clone https://github.com/truongdatdev/junto.git
cd junto
bun install
bun run check
bun run smoke
bun run build
```

`bun run build` writes a single Node compatible file to `dist/index.js`. `bun run fixtures` refreshes the demo datasets. Read [docs/architecture.md](docs/architecture.md) for module boundaries and the data flow.

## Documentation

- [Quick start](docs/quickstart.md)
- [Methodology](docs/methodology.md)
- [MCP client setup](docs/mcp-clients.md)
- [Data sources](docs/data-sources.md)
- [Architecture](docs/architecture.md)
- [FAQ](docs/faq.md)
- [Changelog](CHANGELOG.md)

## Contributing

Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before you start. Report security problems through [SECURITY.md](SECURITY.md), not a public issue.

## License

MIT. See [LICENSE](LICENSE).

## Disclaimer

Junto is a research tool. It is not a registered investment adviser, broker, or fiduciary. The output is not investment advice, an offer, or a solicitation. It does not account for your objectives, financial situation, or needs. Markets involve risk, including loss of principal. Verify all data and consult a qualified professional before making any decision.