@stabem/newsintel-mcp 0.1.0

package/README.md

@@ -0,0 +1,217 @@
+# NewsIntel MCP Server
+
+[![MCP](https://img.shields.io/badge/MCP-compatible-6f42c1)](https://modelcontextprotocol.io)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-339933)](https://nodejs.org)
+
+MCP server para integrações dinâmicas com NewsIntel usando **token do próprio usuário** em cada chamada.
+
+> Objetivo: permitir que qualquer cliente de IA (secretaria, assistentes, apps de terceiros) use o mesmo contrato MCP, sem hardcode por usuário.
+
+---
+
+## Sumário
+
+- [Arquitetura](#arquitetura)
+- [Pré-requisitos](#pré-requisitos)
+- [Instalação](#instalação)
+- [Executar](#executar)
+- [Configuração](#configuração)
+- [Ferramentas MCP](#ferramentas-mcp)
+- [Exemplos de uso](#exemplos-de-uso)
+- [Modelo de erros](#modelo-de-erros)
+- [Segurança](#segurança)
+- [Desenvolvimento](#desenvolvimento)
+- [FAQ](#faq)
+
+---
+
+## Arquitetura
+
+O servidor roda via `stdio` e atua como **proxy fino** para a API NewsIntel:
+
+1. Cliente MCP chama uma tool
+2. Tool recebe `apiToken` do usuário final
+3. Servidor chama endpoint NewsIntel correspondente
+4. Retorna JSON estruturado para o cliente MCP
+
+Sem estado local por usuário, sem sessão persistente no MCP.
+
+---
+
+## Pré-requisitos
+
+- Node.js `>= 22`
+- Acesso HTTP ao endpoint da NewsIntel API
+- Token de usuário NewsIntel (`ni_live_...`)
+
+---
+
+## Instalação
+
+```bash
+cd integrations/newsintel-mcp
+npm install
+```
+
+---
+
+## Executar
+
+```bash
+npm start
+```
+
+Isso inicia o servidor MCP em `stdio` (modo esperado por clientes MCP).
+
+---
+
+## Configuração
+
+Variáveis de ambiente suportadas:
+
+| Variável | Obrigatória | Default | Descrição |
+|---|---:|---|---|
+| `NEWSINTEL_API_BASE` | não | `https://newsintelapi.com` | Base URL da API NewsIntel |
+
+Exemplo:
+
+```bash
+NEWSINTEL_API_BASE=https://newsintelapi.com npm start
+```
+
+---
+
+## Ferramentas MCP
+
+### 1) `newsintel_sync_profile`
+Sincroniza/personaliza o perfil do usuário.
+
+**Input**
+- `apiToken` (string, obrigatório)
+- `mode` (`manual` | `x-browser` | `x-api`, opcional, default `manual`)
+- `topics` (string[], opcional)
+- `free_text` (string, opcional)
+- `x_username` (string, opcional)
+
+**Backend**
+- `POST /v1/profile/sync`
+
+---
+
+### 2) `newsintel_get_profile`
+Busca perfil/interesses atuais do usuário.
+
+**Input**
+- `apiToken` (string, obrigatório)
+
+**Backend**
+- `GET /v1/profile`
+
+---
+
+### 3) `newsintel_get_news_briefing`
+Busca notícias personalizadas com filtros.
+
+**Input**
+- `apiToken` (string, obrigatório)
+- `topics` (string[], opcional)
+- `country` (string, opcional, ex: `BR`, `US`)
+- `lang` (string[], opcional, ex: `['pt','en']`)
+- `limit` (number, opcional, `5..50`, default `20`)
+
+**Backend**
+- `GET /v1/news/search`
+
+---
+
+## Exemplos de uso
+
+### Sync manual com tópicos explícitos
+
+```json
+{
+  "apiToken": "ni_live_xxx",
+  "mode": "manual",
+  "topics": ["spfc", "crypto", "macro"]
+}
+```
+
+### Buscar perfil
+
+```json
+{
+  "apiToken": "ni_live_xxx"
+}
+```
+
+### Buscar briefing BR/PT
+
+```json
+{
+  "apiToken": "ni_live_xxx",
+  "topics": ["spfc", "mercados"],
+  "country": "BR",
+  "lang": ["pt"],
+  "limit": 20
+}
+```
+
+---
+
+## Modelo de erros
+
+Erros de API são retornados como:
+
+```text
+newsintel_api_error <status>: <payload-json-truncado>
+```
+
+Exemplos comuns:
+- `401/403`: token inválido ou sem permissão
+- `429`: rate limit
+- `5xx`: indisponibilidade temporária
+
+Recomendado no cliente:
+- retry com backoff para `429/5xx`
+- refresh/reauth para `401/403`
+
+---
+
+## Segurança
+
+- Trate `apiToken` como segredo.
+- Não salve token em logs, analytics ou mensagens de erro públicas.
+- Prefira injeção via secrets manager.
+- Se houver suspeita de vazamento: rotacione o token imediatamente.
+
+---
+
+## Desenvolvimento
+
+Estrutura:
+
+```text
+integrations/newsintel-mcp/
+├── server.mjs
+├── package.json
+└── README.md
+```
+
+Checagem rápida de sintaxe:
+
+```bash
+node --check server.mjs
+```
+
+---
+
+## FAQ
+
+**Preciso de um MCP por usuário?**
+- Não. O mesmo servidor atende múltiplos usuários via `apiToken` por chamada.
+
+**Posso apontar para outra API base (staging)?**
+- Sim, usando `NEWSINTEL_API_BASE`.
+
+**Esse MCP guarda estado?**
+- Não. É stateless; toda personalização vem da API NewsIntel.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@stabem/newsintel-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server for NewsIntel — personalized news intelligence for AI agents",
+  "mcpName": "io.github.stabem/newsintel",
+  "main": "server.mjs",
+  "bin": {
+    "newsintel-mcp": "server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "test": "node --test server.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "newsintel",
+    "news",
+    "ai-agent",
+    "claude",
+    "llm",
+    "briefing"
+  ],
+  "author": "stabem",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stabem/newsintel-api.git",
+    "directory": "integrations/newsintel-mcp"
+  },
+  "homepage": "https://github.com/stabem/newsintel-api/tree/main/integrations/newsintel-mcp",
+  "bugs": {
+    "url": "https://github.com/stabem/newsintel-api/issues"
+  },
+  "files": [
+    "server.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.2"
+  }
+}

package/server.mjs

@@ -0,0 +1,179 @@
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const API_BASE = process.env.NEWSINTEL_API_BASE || 'https://newsintelapi.com';
+
+async function apiRequest({ apiToken, method = 'GET', path, body }) {
+  if (!apiToken || typeof apiToken !== 'string') {
+    throw new Error('apiToken is required');
+  }
+
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { raw: text };
+  }
+
+  if (!res.ok) {
+    throw new Error(`newsintel_api_error ${res.status}: ${JSON.stringify(data).slice(0, 600)}`);
+  }
+
+  return data;
+}
+
+const server = new Server(
+  {
+    name: 'newsintel-mcp-server',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'newsintel_sync_profile',
+        description: 'Sync/personalize NewsIntel profile dynamically for a user token',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            apiToken: { type: 'string', description: 'User API token (ni_live_...)' },
+            mode: { type: 'string', enum: ['manual', 'x-browser', 'x-api'], default: 'manual' },
+            topics: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Optional explicit interests/topics',
+            },
+            free_text: { type: 'string' },
+            x_username: { type: 'string' },
+          },
+          required: ['apiToken'],
+        },
+      },
+      {
+        name: 'newsintel_get_profile',
+        description: 'Fetch user profile/interests for a user token',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            apiToken: { type: 'string', description: 'User API token (ni_live_...)' },
+          },
+          required: ['apiToken'],
+        },
+      },
+      {
+        name: 'newsintel_get_news_briefing',
+        description: 'Fetch personalized news with optional topics/country/language filters',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            apiToken: { type: 'string', description: 'User API token (ni_live_...)' },
+            topics: { type: 'array', items: { type: 'string' } },
+            country: { type: 'string', description: 'Country code, e.g. BR or US' },
+            lang: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Languages, e.g. ["pt","en"]',
+            },
+            limit: { type: 'number', minimum: 5, maximum: 50, default: 20 },
+          },
+          required: ['apiToken'],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  if (name === 'newsintel_sync_profile') {
+    const body = {
+      mode: args.mode || 'manual',
+      topics: Array.isArray(args.topics) ? args.topics : undefined,
+      free_text: typeof args.free_text === 'string' ? args.free_text : undefined,
+      x_username: typeof args.x_username === 'string' ? args.x_username : undefined,
+    };
+
+    const data = await apiRequest({
+      apiToken: args.apiToken,
+      method: 'POST',
+      path: '/v1/profile/sync',
+      body,
+    });
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+  }
+
+  if (name === 'newsintel_get_profile') {
+    const data = await apiRequest({
+      apiToken: args.apiToken,
+      method: 'GET',
+      path: '/v1/profile',
+    });
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+  }
+
+  if (name === 'newsintel_get_news_briefing') {
+    const params = new URLSearchParams();
+    params.set('limit', String(Math.max(5, Math.min(50, Number(args.limit || 20)))));
+
+    if (Array.isArray(args.topics) && args.topics.length > 0) {
+      params.set('topics', args.topics.join(','));
+    }
+
+    if (typeof args.country === 'string' && args.country.trim()) {
+      params.set('country', args.country.trim().toUpperCase());
+    }
+
+    if (Array.isArray(args.lang) && args.lang.length > 0) {
+      params.set('lang', args.lang.join(','));
+    }
+
+    const data = await apiRequest({
+      apiToken: args.apiToken,
+      method: 'GET',
+      path: `/v1/news/search?${params.toString()}`,
+    });
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+export { server, apiRequest };
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}