# Slingrs ERP (Solutions) MCP Server

[![MCP](https://img.shields.io/badge/MCP-1.0-blue.svg)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-green.svg)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-UNLICENSED-lightgrey.svg)](LICENSE)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects Claude and other AI assistants to the **Slingrs ERP (Solutions)** API.

This server exposes ERP endpoints (sales orders, inventory, production, purchasing, shipments, and custom entities) as tools that AI assistants can directly query and execute.

---

## ✨ Features

- **Dynamic OpenAPI Loading**: Parses OpenAPI specifications at startup so new endpoints and schema changes become immediately available without reinstalling.
- **Claude Desktop Extension**: Packages as a standard `.mcpb` bundle with a user-friendly UI for entering credentials and configuring URLs.
- **Discovery Mode**: Optional catalog discovery mode (`SOLUTIONS_DYNAMIC_TOOLS=true`) to keep the active tool list compact while allowing on-demand endpoint lookup.
- **Cross-Platform**: Works seamlessly across macOS, Linux, and Windows with Node.js 20+.

---

## 📋 Prerequisites

- **Node.js** >= 20.0.0
- A 32-character **Slingrs ERP API Access Token** (obtainable from your ERP profile/settings).

---

## ⚙️ Configuration & Environment Variables

All settings can be configured via environment variables or through the Claude Desktop extension settings interface.

| Variable | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `SOLUTIONS_API_TOKEN` | `string` | *(Required)* | 32-character Slingrs ERP API access token. |
| `SOLUTIONS_API_BASE_URL` | `string` | `https://solutions.slingrs.io/prod/runtime/api` | Base URL for the Slingrs ERP API. |
| `SOLUTIONS_OPENAPI_SPEC` | `string` | `https://raw.githubusercontent.com/fmaximiranda/solutions-mcp/main/openapi.json` | URL of the OpenAPI JSON specification. |
| `SOLUTIONS_DYNAMIC_TOOLS` | `boolean` | `false` | When `true`, exposes discovery tools instead of registering every endpoint upfront. |
| `SOLUTIONS_DEBUG` | `boolean` | `false` | Enables verbose diagnostic logging to stderr. |

---

## 🚀 Setup & Usage

### 1. Claude Desktop (Extension Bundle `.mcpb`)

1. Build or download the `solutions-1.0.0.mcpb` extension bundle from the `dist/` directory.
2. Double-click the `.mcpb` file or install it via Claude Desktop **Settings > Extensions > Install Extension**.
3. In Claude Desktop, open **Settings > Extensions > Solutions** and paste your 32-character **Access Token**.
4. (Optional) Customize the API base URL or OpenAPI specification URL if you are connecting to a custom environment.

### 2. Claude Desktop (Manual JSON Configuration)

Add the following to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "solutions": {
      "command": "npx",
      "args": ["-y", "@fmiranda5/solutions-mcp"],
      "env": {
        "SOLUTIONS_API_TOKEN": "YOUR_32_CHAR_ACCESS_TOKEN_HERE"
      }
    }
  }
}
```

Or when running from a local checkout:

```json
{
  "mcpServers": {
    "solutions": {
      "command": "node",
      "args": ["/path/to/solutions/index.js"],
      "env": {
        "SOLUTIONS_API_TOKEN": "YOUR_32_CHAR_ACCESS_TOKEN_HERE"
      }
    }
  }
}
```

### 3. CLI & Other MCP Clients

Run directly via `npx`:

```bash
export SOLUTIONS_API_TOKEN="YOUR_32_CHAR_ACCESS_TOKEN_HERE"
npx @fmiranda5/solutions-mcp
```

Or execute locally with Node:

```bash
export SOLUTIONS_API_TOKEN="YOUR_32_CHAR_ACCESS_TOKEN_HERE"
node index.js
```

---

## 🛠️ Development & Building

### Install Dependencies

```bash
npm install
```

### Build Extension Bundle (`.mcpb`)

Builds the production bundle into `dist/solutions-<version>.mcpb`:

```bash
npm run build
```

### OpenAPI Specification Processing

If you need to customize, filter, or enhance the raw OpenAPI specification from Slingrs (e.g. inject pagination query parameters `_size`, `_offset`, `_sortField` or prune redundant global actions):

1. Place your raw spec as `openapi.json`.
2. Run the transformation script:
   ```bash
   node modificar_v2.js
   ```
   *(To preview actions without writing changes, pass `--report`: `node modificar_v2.js --report`)*
3. The cleaned specification will be saved to `openapi_modificado.json`.

---

## 📦 Publishing to NPM

To publish a new version to the npm registry:

1. Update the version in `package.json` and `manifest.json`.
2. Rebuild the bundle:
   ```bash
   npm run build
   ```
3. Publish to npm:
   ```bash
   npm publish --access public
   ```

---

## 👤 Author & Support

- **Author**: Maxi Miranda ([fmiranda@slingr.io](mailto:fmiranda@slingr.io))
- **Company**: [Slingr](https://slingr.io/)
- **Repository**: [github.com/fmaximiranda/solutions-mcp](https://github.com/fmaximiranda/solutions-mcp)