Metadata-Version: 2.5
Name: noterp-mcp
Version: 0.1.1
Summary: MCP server con tools para consultar endpoints del sitio NotERP
Author-email: GlobalSoft <rarzate@globalsoft.lat>
Keywords: erp,mcp,model-context-protocol,noterp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# NotERP MCP

Servidor [MCP](https://modelcontextprotocol.io) que expone tools para consultar
empleados, comprobantes, ingresos, gastos y metadatos SAT de **NotERP**.

## Suscripción requerida

Este MCP requiere una **suscripción activa**. Obtén tu token de suscripción en
**https://globalsoft.lat/pages/noterp** y configúralo en la variable `SUBSCRIPTION_TOKEN`.
Sin un token válido las tools no se ejecutan.

## Tools

| Tool | Descripción |
| --- | --- |
| `listar_empleados` | Lista empleados de NotERP. Params: `hoja`, `all_empleados` (0/1), `id_empleado`, `estatus` (ACTIVO/INACTIVO). |
| `consultar_comprobantes` | Consulta comprobantes/facturas. Params: `id_comprobante`, `folio`, `estatus`, `concepto`, `uuid`, `num_comprobante`, `tipo_documento`, `metodo_pago`, `fecha_timbrado_inicio`, `fecha_timbrado_fin`, `hoja`, `por_pagina`. |
| `consultar_gastos` | Consulta gastos. Params: `id_gasto`, `folio`, `estatus`, `concepto`, `rfc`, `proyecto`, `centro_costo`, `fecha_operacion_inicio`, `fecha_operacion_fin`, `monto_min`, `monto_max`, `hoja`, `por_pagina`. |
| `consultar_ingresos` | Consulta ingresos. Params: `id_ingreso`, `folio`, `estatus`, `concepto`, `rfc`, `cliente`, `fecha_operacion_inicio`, `fecha_operacion_fin`, `fecha_factura_inicio`, `fecha_factura_fin`, `monto_min`, `monto_max`, `hoja`, `por_pagina`. |
| `consultar_metadata_sat` | Consulta metadatos SAT de los comprobantes. Params: `rfc_emisor`, `rfc_receptor`, `uuid`, `estatus`, `fecha_emision_inicio`, `fecha_emision_fin`, `monto_min`, `monto_max`, `hoja`, `por_pagina`. |

## Requisitos

- [uv](https://docs.astral.sh/uv/) (incluye `uvx`).
- Datos del sitio NotERP: `BASE_URL` y, si aplica, `TOKEN`.
- Token de suscripción: `SUBSCRIPTION_TOKEN` (ver arriba).

## Instalación rápida

No requiere instalación previa; `uvx` descarga y ejecuta el paquete:

```sh
uvx noterp-mcp==0.1.1
```

El transporte por defecto es `stdio`, que es lo que usan los clientes MCP. El servidor
lee las credenciales desde variables de entorno.

## Variables de entorno

| Variable | Obligatoria | Descripción |
| --- | --- | --- |
| `BASE_URL` | Sí | URL base del sitio NotERP. Ej: `https://noterp.ejemplo.com` |
| `TOKEN` | No | Token de autenticación; viaja dentro de la ruta del endpoint. |
| `SUBSCRIPTION_TOKEN` | Sí | Token de suscripción de la plataforma (https://globalsoft.lat/pages/noterp). |

## Configuración por cliente

Reemplaza `<url_noterp>`, `<token>` y `<subscription_token>` por tus valores.

### Claude Code

```sh
claude mcp add noterp \
  -e BASE_URL=<url_noterp> \
  -e TOKEN=<token> \
  -e SUBSCRIPTION_TOKEN=<subscription_token> \
  -- uvx noterp-mcp==0.1.1
```

### Codex

CLI:

```sh
codex mcp add noterp \
  --env BASE_URL=<url_noterp> \
  --env TOKEN=<token> \
  --env SUBSCRIPTION_TOKEN=<subscription_token> \
  -- uvx noterp-mcp==0.1.1
```

O en `~/.codex/config.toml` (o `.codex/config.toml` en el proyecto):

```toml
[mcp_servers.noterp]
command = "uvx"
args = ["noterp-mcp==0.1.1"]
env = { BASE_URL = "<url_noterp>", TOKEN = "<token>", SUBSCRIPTION_TOKEN = "<subscription_token>" }
```

### Antigravity

En `~/.gemini/config/mcp_config.json` (global) o `.agents/mcp_config.json` (workspace):

```json
{
  "mcpServers": {
    "noterp": {
      "command": "uvx",
      "args": ["noterp-mcp==0.1.1"],
      "env": {
        "BASE_URL": "<url_noterp>",
        "TOKEN": "<token>",
        "SUBSCRIPTION_TOKEN": "<subscription_token>"
      }
    }
  }
}
```

### opencode

En `opencode.jsonc` (o `~/.config/opencode/opencode.json`):

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "noterp": {
      "type": "local",
      "command": ["uvx", "noterp-mcp==0.1.1"],
      "environment": {
        "BASE_URL": "<url_noterp>",
        "TOKEN": "<token>",
        "SUBSCRIPTION_TOKEN": "<subscription_token>"
      },
      "enabled": true
    }
  }
}
```

### Otros clientes (formato genérico `mcpServers`)

Válido para Claude Desktop y otros clientes que usan el formato `mcpServers`:

```json
{
  "mcpServers": {
    "noterp": {
      "command": "uvx",
      "args": ["noterp-mcp==0.1.1"],
      "env": {
        "BASE_URL": "<url_noterp>",
        "TOKEN": "<token>",
        "SUBSCRIPTION_TOKEN": "<subscription_token>"
      }
    }
  }
}
```

## Troubleshooting

- **`Error de configuración: Falta la variable de entorno ...`**: el proceso no ve las
  variables requeridas. Verifica que estén definidas en el bloque `env`/`environment` del
  cliente correspondiente (o en un `.env` si ejecutas desde el repo).
- **Las tools devuelven un JSON de error de suscripción**: el `SUBSCRIPTION_TOKEN` no es
  válido, está expirado o la póliza no está activa. Obtén/renueva el token en
  https://globalsoft.lat/pages/glpi. La validación es *fail-closed* y el resultado válido
  se cachea 60s.
- **`BASE_URL` mal formada**: debe ser la raíz del sitio NotERP (ej.
  `https://noterp.ejemplo.com`) y sin una barra final sobrante.
- **Verificar que el paquete arranca** (con las variables ya exportadas en el shell):

  ```sh
  uvx noterp-mcp==0.1.1
  ```

  Si faltan variables, el proceso termina con `SystemExit` y el mensaje de configuración;
  es el comportamiento esperado.
