# mcp-avangenio-services

[![npm version](https://img.shields.io/npm/v/mcp-avangenio-services.svg)](https://www.npmjs.com/package/mcp-avangenio-services)
[![CI](https://github.com/jesusr00/mcp-avangenio-services/actions/workflows/ci.yml/badge.svg)](https://github.com/jesusr00/mcp-avangenio-services/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

[MCP](https://modelcontextprotocol.io) server (**stdio** transport) that exposes the **status of Avangenio's services**. It downloads the plain text published at `https://status.avangenio.com/data.txt`, parses it, and returns it as normalized JSON.

## Tool

### `avangenio_get_status`

Takes no arguments. Returns the current status with normalized values (booleans and numbers) plus a `raw` object with the original pairs exactly as they arrive from the source.

```json
{
  "lastUpdate": "Tue Aug  4 07:30:01 CDT 2026",
  "internetStatus": "OK",
  "internetOk": true,
  "bandwidthMbps": 31.8,
  "batteryPercent": 21,
  "electricalServiceOk": false,
  "raw": {
    "Ultima actualizacion": "Tue Aug  4 07:30:01 CDT 2026",
    "Internet Status": "OK",
    "Ancho de Banda por Usuario": "31.80 Mbps",
    "Estado de las baterías": "21.00%",
    "Servicio Eléctrico Estatal": "NO"
  }
}
```

Any missing or uninterpretable field is returned as `null`; unknown keys are kept only in `raw`, so the tool does not break if the source adds new lines.

## Installation

The server is published to npm, so you don't need to clone or build anything —
point your MCP client at it with `npx` and it will be downloaded on first use.

### Claude Code

Add it with the CLI:

```bash
claude mcp add avangenio -- npx -y mcp-avangenio-services
```

Or add it manually to your `.mcp.json`:

```json
{
  "mcpServers": {
    "avangenio": {
      "command": "npx",
      "args": ["-y", "mcp-avangenio-services"]
    }
  }
}
```

### Claude Desktop

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "avangenio": {
      "command": "npx",
      "args": ["-y", "mcp-avangenio-services"]
    }
  }
}
```

Then restart Claude Desktop.

### Other MCP clients

Any stdio-capable MCP client works. Use:

- **command:** `npx`
- **args:** `["-y", "mcp-avangenio-services"]`

### Global install (optional)

If you prefer a fixed binary instead of `npx`:

```bash
npm install -g mcp-avangenio-services
```

The command is then available as `mcp-avangenio-services`, so your MCP config
becomes `"command": "mcp-avangenio-services"` with no `args`.

## Requirements

- **Node.js 18 or higher** (uses native `fetch` and `AbortSignal.timeout`).
- **Network access** to the status endpoint. The panel may be **IP-restricted**
  on the server (nginx); if you get a `403` error, run the MCP from a network
  with allowed access to `status.avangenio.com`.

## Try it out

Launch the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
against the published package and call `avangenio_get_status`:

```bash
npx @modelcontextprotocol/inspector npx -y mcp-avangenio-services
```

## Development

Built with TypeScript + `@modelcontextprotocol/sdk` over stdio, bundled with
`tsdown`, tested with Vitest, and managed with pnpm. It mirrors the structure and
conventions of [`mcp-server-redmine`](https://github.com/jesusr00/mcp-server-redmine).

```bash
git clone https://github.com/jesusr00/mcp-avangenio-services.git
cd mcp-avangenio-services
pnpm install
pnpm build          # generates dist/index.mjs (ESM) and dist/index.js (CJS)
```

To run your local build from an MCP client, point it at the built entry point:

```json
{
  "mcpServers": {
    "avangenio": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-avangenio-services/dist/index.mjs"]
    }
  }
}
```

### Scripts

```bash
pnpm dev            # build in watch mode
pnpm test           # tests (Vitest)
pnpm test:coverage
pnpm typecheck      # tsc --noEmit
pnpm lint           # eslint (zero warnings)
pnpm format         # prettier --write
```

### Structure

```
src/
├── index.ts                 # entry: McpServer + StdioServerTransport
├── client/avangenio.ts      # downloads the data.txt
├── tools/
│   ├── index.ts             # registerAllTools
│   ├── shared.ts            # ok / err / withErrorHandling
│   └── status/
│       ├── definition.ts    # tool metadata
│       ├── index.ts         # server registration
│       ├── parse.ts         # pure parser (text -> AvangenioStatus)
│       ├── schema.ts        # input schema (zod)
│       └── status.ts        # handler
└── types/                   # ToolResult, AvangenioStatus
```

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for
the development workflow and guidelines. To report a vulnerability, follow
[SECURITY.md](./SECURITY.md).

## License

[MIT](./LICENSE)