# Tarkov MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Escape From Tarkov game
data through the [tarkov.dev](https://tarkov.dev) GraphQL API.

## Overview

This MCP server allows AI assistants to access detailed information about Escape From Tarkov,
including items, traders, maps, quests, crafting recipes, and much more. It's designed to be a
comprehensive resource for players, developers, and AI applications that need Tarkov game data.

## Features

### Available Tools

The server provides 19 different tools to access various aspects of Tarkov data:

#### Core Game Data

- **`achievement`** - Returns all achievements from Escape From Tarkov
- **`items`** - Returns comprehensive item data including stats, prices, and properties
- **`ammo`** - Returns detailed ammunition information including ballistics
- **`armor-materials`** - Returns armor material properties and durability data

#### Trading & Economy

- **`barter`** - Returns all barter trades available from traders
- **`traders`** - Returns trader information, levels, and offers
- **`flea-market`** - Returns flea market configuration and fees

#### Crafting & Hideout

- **`crafts`** - Returns all crafting recipes and requirements
- **`hideout-stations`** - Returns hideout station information and upgrades

#### Quests & Progression

- **`tasks`** - Returns all quests/tasks with objectives and rewards
- **`quest-items`** - Returns special quest-only items
- **`skills`** - Returns player skills information
- **`player-levels`** - Returns player level progression data
- **`mastering`** - Returns weapon mastering requirements

#### Maps & Locations

- **`maps`** - Returns detailed map information including extracts, spawns, and loot
- **`bosses`** - Returns boss information including health, equipment, and drops
- **`loot-containers`** - Returns loot container locations and spawn chances
- **`stationary-weapons`** - Returns stationary weapon information

#### System Information

- **`server-status`** - Returns current Tarkov server status and messages

## Installation

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Configure environment variables (optional):
   ```bash
   TARKOV_API_ENDPOINT=https://api.tarkov.dev/graphql
   TARKOV_LANG=en
   ```

## Usage

### Running the Server

```bash
npm start
```

The server will start and listen for MCP connections.

### Configuration

The server can be configured through environment variables:

- `TARKOV_API_ENDPOINT` - GraphQL API endpoint (default: https://api.tarkov.dev/graphql)
- `TARKOV_LANG` - Language code for localized content (default: en)

### Tool Details

#### achievement

Returns achievement data including:

- Achievement name and description
- Completion percentages
- Rarity information
- Side requirements (PMC/SCAV)

#### items

Returns comprehensive item data including:

- Basic properties (name, description, size, weight)
- Market prices and trends
- Item properties specific to type (weapons, armor, consumables, etc.)
- Trading information (barters, cash offers)
- Quest usage
- Crafting recipes

#### ammo

Returns ammunition data including:

- Ballistic properties (damage, penetration, accuracy)
- Armor damage and fragmentation
- Recoil and velocity modifiers
- Tracer information

#### barter

Returns barter trade information including:

- Required items and quantities
- Reward items and quantities
- Trader and level requirements
- Task unlock requirements

#### traders

Returns trader information including:

- Trader levels and requirements
- Available barters and cash offers
- Reputation levels and bonuses
- Insurance and repair rates

#### tasks

Returns quest/task data including:

- Objectives and requirements
- Rewards (items, experience, trader standing)
- Prerequisites and unlock conditions
- Map-specific information

#### maps

Returns detailed map information including:

- Spawn points and extracts
- Loot container and loose loot locations
- Boss spawn information
- Hazards and special zones
- Key requirements

#### crafts

Returns crafting recipe data including:

- Required materials and quantities
- Produced items
- Crafting station and level requirements
- Crafting duration

#### hideout-stations

Returns hideout station information including:

- Upgrade requirements (items, skills, trader levels)
- Station bonuses and effects
- Crafting capabilities
- Construction time and costs

## API Reference

All tools return data in JSON format directly from the tarkov.dev GraphQL API. The data structure
follows the GraphQL schema definitions.

### Error Handling

The server handles various error conditions:

- Network connectivity issues
- API rate limiting
- Invalid GraphQL queries
- Missing or malformed data

## Development

### Project Structure

```
src/
├── config/          # Configuration management
├── logger/          # Logging utilities
├── tools/           # MCP tool implementations
│   └── items/       # Individual tool modules
│       ├── achievements/
│       ├── ammo/
│       ├── barter/
│       └── ...
└── server.js        # Main MCP server
```

### Adding New Tools

1. Create a new directory under `src/tools/items/`
2. Implement `loader.js` with GraphQL query
3. Implement `index.js` with tool definition
4. Add to `src/tools/items/index.js` exports

### Code Style

The project uses:

- ESLint for code linting
- Prettier for code formatting

Run formatting and linting:

```bash
npm run format
npm run lint
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [tarkov.dev](https://tarkov.dev) for providing the comprehensive Tarkov API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- The Escape From Tarkov community for data validation and feedback

## Support

For issues and questions:

- Check the [tarkov.dev API documentation](https://tarkov.dev/api)
- Open an issue on this repository
- Join the community discussions