# Pricempire MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for querying your
[Pricempire](https://pricempire.com) CS2 (Counter-Strike 2) trader portfolio: total value,
breakdowns by category, top holdings, cross-marketplace price comparison, and price history.

Built on [`nt4f04uNd/pricempire`](https://github.com/nt4f04uNd/pricempire), a fork of the official
[`@pricempire/api`](https://www.npmjs.com/package/@pricempire/api) Node.js client that adds
support for the real **Trader Portfolio API** (`/v4/trader/*`), which the published npm package
does not implement.

This server is **on-demand**: it can both inspect Pricempire data and, for the Trader API
surface exposed by the installed JS client fork, perform write operations such as creating
portfolios, managing transactions, and maintaining price alerts.
It does not run alerts, bots, or schedulers by itself.

## What it is useful for

This MCP server is useful when you want an LLM agent to help you inspect your Pricempire
portfolio without manually clicking around the UI or exporting data.

Typical use cases:

- check your total portfolio value, invested amount, unrealized P/L, and ROI
- see your most valuable items and how concentrated your portfolio is
- break down value by category such as skins, containers, agents, gloves, and charms
- compare item prices across marketplaces
- inspect historical price data for a specific item or marketplace source
- create/update/delete trader portfolios and transactions
- create/update/delete price alerts
- access trader insights, trends, and raw v3/v4 endpoints
- build portfolio summaries or visualizations in a separate skill layer

## Trader transaction notes

The live Pricempire Trader API has two quirks that matter for transaction writes:

- `asset_id` alone is not reliable for item-specific transactions. For accurate imports, prefer
  passing `asset_item_id` as well.
- transaction prices are effectively expected in **cents**, not floating-point USD values. For
  example, `0.70 USD` should be sent as `70`.

Because of that, `trader_add_transaction` in this MCP server behaves defensively:

- if you provide `asset_item_id`, it creates the transaction and immediately rebinds it to the
  concrete item with a follow-up update
- if you omit `asset_item_id` and provide a single `market_hash_name`, it returns a ready-to-open
  `pricempire.com/api-data/...` lookup URL
- if you omit `asset_item_id` and provide multiple `market_hash_names`, it returns a one-shot
  browser-console script that resolves all required IDs in one run

## How to start using it

The normal flow is:

1. Build this repository and configure your Pricempire API key.
2. Register the server in your MCP client.
3. Ask your agent questions about your portfolio.

Examples of the kinds of prompts this enables:

- "What's my portfolio worth right now?"
- "Show me my top 10 most valuable items."
- "How much of my portfolio is in cases versus skins?"
- "Which items have the biggest unrealized losses?"
- "Visualize my portfolio by category."

## Visualization skills

If you want a higher-level presentation layer on top of this MCP server, see
[`pricempire-mcp-cs-tools`](https://github.com/nt4f04uNd/pricempire-mcp-cs-tools).

That repository contains CS2-specific skills, prompts, and example visualizations built on top of
the tools exposed here. The intended split is:

- `pricempire-mcp`: data access and portfolio analysis tools
- `pricempire-mcp-cs-tools`: visualization-oriented skill layer

## Prerequisites

- Node.js 18 or newer
- A Pricempire API key with **Trader tier** access (portfolio value/holdings are a Trader-tier
  feature; see [pricempire.com](https://pricempire.com/) account settings). Cross-marketplace
  price lookup tools (`get_item_prices`, `get_price_history`) additionally require v3/v4 market
  data access depending on your plan.

## Setup

```bash
npm install
cp .env.example .env
# edit .env and set PRICEMPIRE_API_KEY (and optionally DEFAULT_CURRENCY / DEFAULT_SOURCES)
npm run build
```

`.env` is git-ignored — never commit real API keys. `.env.example` documents each variable with
placeholder values only.

### Environment variables

| Variable           | Required | Description                                                                 |
| ------------------ | -------- | ----------------------------------------------------------------------------- |
| `PRICEMPIRE_API_KEY` | Yes      | Your Pricempire API key (UUID v4).                                          |
| `DEFAULT_CURRENCY`  | No       | Default currency code (e.g. `USD`, `EUR`). Defaults to `USD`.               |
| `DEFAULT_SOURCES`   | No       | Comma-separated default marketplace sources (e.g. `buff163,steam`) for `get_item_prices`. Defaults to `buff163,steam`. |

Portfolios themselves aren't selected via env vars — the account tied to `PRICEMPIRE_API_KEY` may
have multiple named portfolios (e.g. "Main portfolio", "Secondary portfolio"); tools default to all
of them combined, or accept an optional `portfolio` name/slug filter per call.

## Running

```bash
npm run dev     # run directly from TypeScript source with tsx (auto-reload)
npm run build   # compile to dist/
npm start       # run the compiled server (node dist/index.js)
```

The server communicates over stdio, per the MCP stdio transport convention.

## Registering with an MCP client

Add an entry pointing at the built `dist/index.js`. Example `mcp.json`-style configuration:

```json
{
  "mcpServers": {
    "pricempire": {
      "command": "node",
      "args": ["/absolute/path/to/pricempire-mcp/dist/index.js"],
      "env": {
        "PRICEMPIRE_API_KEY": "your-pricempire-api-key",
        "DEFAULT_CURRENCY": "USD",
        "DEFAULT_SOURCES": "buff163,steam"
      }
    }
  }
}
```

Adjust the path and the exact config file/format for your MCP client (e.g. Copilot CLI, Claude
Desktop, etc.).

## Quick start checklist

1. Copy `.env.example` to `.env`.
2. Set `PRICEMPIRE_API_KEY`.
3. Run `npm install`.
4. Run `npm run build`.
5. Register `dist/index.js` in your MCP client.
6. Restart or reload the MCP client if needed.
7. Ask a portfolio question such as "Analyze my portfolio."

## Available tools

| Tool family | Description |
| ----------- | ----------- |
| `get_portfolio_value`, `list_portfolio_items`, `get_item_prices`, `get_price_history`, `analyze_portfolio` | Opinionated high-level tools for portfolio analysis and visualization workflows. |
| `v3_*` | Raw parity tools for the JS client's `v3` methods: all items, basic/advanced data, inventories, structured items, item IDs, and self inventory. |
| `v4_*` | Raw parity tools for the JS client's paid-tier `v4` methods: prices, item metas, item catalog, and item images. |
| `trader_*` | Raw parity tools for the JS client's `v4.trader` methods: portfolios, transactions, alerts, insights, trends, signals, exports, and trader-tier prices. |

Every tool catches API errors (invalid/missing key, rate limiting, plan restrictions, server
errors) and returns a structured error object (`{ error: true, kind, message, detail }`) instead
of throwing, so a calling agent can explain the problem in plain language.

### `trader_add_transaction` expectations

For reliable use of `trader_add_transaction`, pass:

- `price` in cents, for example `70` for `0.70 USD`
- `asset_item_id` whenever you already know the exact item variant

If `asset_item_id` is missing, the tool returns a structured helper payload instead of silently
creating a likely mis-bound transaction.

## Companion Copilot skill

See [`skills/pricempire-portfolio/SKILL.md`](skills/pricempire-portfolio/SKILL.md) for guidance an
LLM agent can use to combine these tools when answering common portfolio questions.

## Notes & limitations

- Portfolio tools (`get_portfolio_value`, `list_portfolio_items`, `analyze_portfolio`) use the
  Pricempire **Trader API** (`/v4/trader/portfolios*`), via the
  [`nt4f04uNd/pricempire`](https://github.com/nt4f04uNd/pricempire) fork depended on in
  `package.json` (`"@pricempire/api": "github:nt4f04uNd/pricempire#codex/trader-portfolio-api"`). The published npm
  package does not implement these endpoints — see that fork's README for details on what was
  added.
- The MCP server also exposes raw-parity tools for the installed fork's `v3`, `v4`, and
  `v4.trader` method surface in addition to the higher-level analysis helpers documented above.
- This is currently built on a fork because upstream `@pricempire/api` does not yet expose the
  Trader Portfolio API. Upstream tracking issue:
  [pricempire/pricempire#3](https://github.com/pricempire/pricempire/issues/3).
- `get_item_prices` and `get_price_history` use the market-wide v3/v4 endpoints from the
  original package and require separate plan access from the Trader tier; if your key doesn't
  have that access, these tools return a structured `auth`/`forbidden` error rather than crashing.