<div align="center">

<img src="./.github/assets/banner.png" alt="GitEquity" width="100%" />

# gitequity-mcp

**Your GitEquity portfolio, inside your AI client.**

[![MCP](https://img.shields.io/badge/MCP-1.29-DCF012?style=for-the-badge&labelColor=0A0A0A)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/Node-20+-339933?style=for-the-badge&labelColor=0A0A0A&logo=node.js&logoColor=white)](https://nodejs.org)
[![License](https://img.shields.io/badge/License-Apache_2.0-DCF012?style=for-the-badge&labelColor=0A0A0A)](LICENSE)

</div>

---

Ask Claude what your portfolio is worth. Ask Cursor to check whether that NVDA position recovered. The MCP server exposes GitEquity as tools any compatible client can call.

Works with Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, Gemini, Grok, Copilot, and anything else that speaks MCP.

---

## Install

### Hosted (nothing to run)

Point your client at the production endpoint:

```json
{
  "mcpServers": {
    "gitequity": {
      "url": "https://gitequity.xyz/api/mcp",
      "transport": "streamable-http"
    }
  }
}
```

### Local via npx

```json
{
  "mcpServers": {
    "gitequity": {
      "command": "npx",
      "args": ["gitequity-mcp"],
      "env": {
        "GITEQUITY_API_URL": "https://api.gitequity.xyz",
        "GITEQUITY_GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}
```

Config file locations: `claude_desktop_config.json` for Claude Desktop, `.cursor/mcp.json` for Cursor. Per-client walkthroughs with screenshots live at [gitequity.xyz/mcp](https://gitequity.xyz/mcp).

### Standalone HTTP

```bash
npx gitequity-mcp --http --port 3001
# → http://localhost:3001/mcp
```

---

## Tools

**Read - execute immediately**

| Tool | Returns |
|---|---|
| `get_vault_balance` | Vault address and USDG balance |
| `get_rwa_portfolio` | Every position with cost basis and current value |
| `get_stock_price` | Live price for one ticker |
| `list_stocks` | All 62 tradeable tickers |
| `get_transactions` | Transaction history |
| `list_repos` | Repositories with the App installed |
| `get_project_status` | Project and bounty state |

**Write - require confirmation**

| Tool | Effect |
|---|---|
| `buy_stock` | Buy a position with USDG |
| `sell_stock` | Sell a position back to USDG |

---

## Why writes need a confirmation code

An AI client can propose a trade. It cannot execute one.

When `buy_stock` or `sell_stock` is called, the server returns a short code instead of moving funds:

```
Confirm this order by commenting in any GitHub issue:

    @gitequitybot confirm 8F2A

Order: buy $NVDA 100 · expires in 10 minutes
```

The trade executes only after that comment appears under your GitHub account. A prompt injection in a web page your assistant happens to read cannot spend your money, because the assistant is not the one holding the authority.

Codes expire after 10 minutes and are single-use.

---

## Development

```bash
pnpm install
pnpm build
pnpm start
```

```
src/
├── index.ts              Server bootstrap, tool registration, transport
├── tools/
│   ├── vault-balance.ts  Balance and vault address
│   ├── rwa-tools.ts      Portfolio, prices, ticker list
│   ├── write-tools.ts    Buy and sell, confirmation flow
│   ├── transactions.ts   History
│   ├── repos.ts          Installed repositories
│   └── project-status.ts Projects and bounties
└── lib/
    ├── github-id.ts      Resolve a token to a numeric GitHub user ID
    ├── vault-reader.ts   On-chain reads
    └── pending.ts        Confirmation code store
```

---

## Environment

| Variable | Required | Default |
|---|---|---|
| `GITEQUITY_API_URL` | yes | - |
| `GITEQUITY_GITHUB_TOKEN` | yes | - |
| `GITEQUITY_RPC_URL` | no | Public Robinhood Chain RPC |

The GitHub token needs `read:user` and nothing more. It is used to resolve your numeric user ID, which is what a vault is keyed on.

---

## License

Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).