ai-news-mcp

Model Context Protocol 서버로, Streamable HTTP를 통해 AI 뉴스 코퍼스에 대한 질문에 답변합니다.

AI 뉴스 에이전트의 데이터 백엔드입니다. 에이전트가 질문하면, 이 도구들이 Supabase Postgres의 news.articles를 검색하고 읽습니다.

모든 도구는 읽기 전용입니다. 읽기 전용 보장 참조.

무상태(stateless): 각 요청은 자체 MCP 서버 인스턴스를 받으며, 요청 간에 유지되는 데이터가 없으므로 세션 ID도 스티키 라우팅도 없습니다. 데이터베이스 풀은 공유됩니다.

코퍼스

Supabase Postgres의 news.articles. 2026-08-24 기준:

도구 설계를 결정하는 두 가지 속성:

• 카테고리는 자유 텍스트이며 파편화되어 있습니다 — 1083개 기사에 668개의 고유 값이 있고, Cybersécurité, Cybersécurité des agents IA, Cybersécurité et agents IA 같은 거의 중복된 값이 있습니다. 정확한 카테고리 일치는 거의 쓸모가 없으므로, search_news는 카테고리를 대소문자 구분 없는 부분 문자열로 일치시킵니다.

• 모든 행의 views는 NULL입니다. 의도적으로 "최다 조회" 도구는 없습니다. 노이즈만 반환할 것이기 때문입니다.

Related MCP server: MCP Server Basic Example

제공 기능

search_news는 320자로 잘린 요약을 반환합니다 — 전체 요약은 모델의 컨텍스트를 빠르게 채웁니다. 기사 하나의 전체 텍스트가 필요하면 get_article을 호출하세요.

파일

• index.js — HTTP(S) 호스트: 라우팅, 인증 검사, TLS, 수명 주기

• mcp-server.js — MCP 서버: 도구, 리소스, 프롬프트

• db.js — Postgres 풀 및 읽기 전용 쿼리 헬퍼

• auth.js — Bearer 토큰 검증

• inspect-cli.js — 개발 헬퍼; 이 서버에 대해 MCP Inspector CLI를 실행

실행

npm install
cp .env.example .env     # then set DATABASE_URL
npm start
# ai-news-mcp listening on http://0.0.0.0:8080/mcp

DATABASE_URL은 필수입니다 — 누락 시 서버는 안내와 함께 종료됩니다. Supabase 트랜잭션 풀러 문자열(포트 6543)을 사용하세요: 대시보드 → Connect → Transaction pooler.

읽기 전용 보장

MCP 엔드포인트는 인증 없이 노출될 수 있으므로, "우리 SQL은 SELECT만 한다"는 충분한 보장이 아닙니다. 두 개의 독립적인 계층:

1. SQL을 받는 도구가 없습니다. 다섯 개 모두 고정된 문을 실행합니다. 호출자 입력은 항상 바인드 파라미터로만 전달되며, 유일하게 보간되는 식별자(list_tags의 tags vs key_words)는 사용 전에 Zod enum으로 제한됩니다.

2. Postgres가 쓰기를 거부합니다. 모든 쿼리는 SET LOCAL statement_timeout과 함께 BEGIN READ ONLY 안에서 실행됩니다(db.js). 세션 수준 SET이 아닌 SET LOCAL을 사용하는 이유는 트랜잭션 풀링에서는 세션 설정이 다음에 해당 백엔드를 넘겨받는 클라이언트에게 누출될 수 있기 때문입니다.

라이브 데이터베이스에 대해 검증됨:

INSERT  blocked: cannot execute INSERT in a read-only transaction
UPDATE  blocked: cannot execute UPDATE in a read-only transaction
DELETE  blocked: cannot execute DELETE in a read-only transaction
DDL     blocked: cannot execute CREATE TABLE in a read-only transaction
SELECT  still works: 1083 rows

심층 방어를 위해, DATABASE_URL을 소유자 대신 전용 읽기 전용 역할로 지정하세요:

CREATE ROLE mcp_reader LOGIN PASSWORD '...';
GRANT USAGE ON SCHEMA news TO mcp_reader;
GRANT SELECT ON news.articles TO mcp_reader;

그러면 트랜잭션 가드가 제거되더라도 이 서버의 버그가 쓰기를 수행할 수 없습니다.

인증

MCP_AUTH_TOKEN이 설정되지 않으면 꺼져 있습니다. 설정하세요. 모든 도구가 데이터베이스를 읽으므로, 열린 엔드포인트는 URL을 찾는 누구나 코퍼스를 쿼리하고 Supabase 할당량을 소진하게 만듭니다. 시작 배너는 토큰이 없을 때 경고합니다.

npm run gen-token          # prints a random 32-byte hex token (64 chars)
MCP_AUTH_TOKEN=<token> npm start

토큰이 설정되면 요청에 Authorization: Bearer <token>이 필요합니다. 스킴은 대소문자를 구분하지 않지만 토큰은 구분합니다. 누락되거나 잘못된 자격 증명은 401과 WWW-Authenticate 챌린지를 받으며, 상수 시간 비교(양쪽을 SHA-256으로 해싱한 후 timingSafeEqual)로 수행되어 응답 타이밍으로 토큰을 복구할 수 없습니다.

32자보다 짧은 토큰은 시작 경고를 발생시킵니다 — 데이터베이스를 보호하는 토큰은 기억하기 쉬운 단어가 되어서는 안 됩니다. gen-token을 사용하세요.

GET /health는 자격 증명을 요구하지 않으므로 플랫폼 상태 확인으로 작동합니다.

검증된 동작:

구성

curl로 시도하기

curl -X POST http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_news","arguments":{"query":"Nvidia","limit":3}}}'

토큰을 설정했다면 -H "authorization: Bearer $MCP_AUTH_TOKEN"을 추가하세요.

Inspector에서 시도하기

npm run inspect:cli -- --method tools/list
npm run inspect:cli -- --method tools/call --tool-name news_stats
npm run inspect:cli -- --method tools/call --tool-name search_news --tool-arg query=Anthropic
npm run inspect:cli -- --method resources/read --uri "news://overview"

웹 UI(npm run inspect)는 Transport Streamable HTTP와 URL http://127.0.0.1:8080/mcp가 필요합니다. 토큰을 설정했다면 Authentication → Header Name Authorization, 값 Bearer <token>을 입력하세요 — 그렇지 않으면 Inspector는 401을 보고 OAuth로 가정하여 이 서버가 구현하지 않는 검색 흐름을 시작합니다.

에이전트에 연결하기

claude mcp add --transport http ai-news https://ai-news-mcp.onrender.com/mcp

토큰이 있으면 --header "Authorization: Bearer <token>"을 추가하세요.

ai_news_analyst 프롬프트는 에이전트의 의도된 진입점입니다: 질문의 언어와 관계없이 답변 전에 검색하도록, 프랑스어로 검색하도록, article_url을 인용하도록, 그리고 일반 지식에 의존하는 대신 코퍼스에 내용이 없을 때는 그렇게 솔직히 말하도록 모델에 지시합니다.

프랑스어 텍스트 검색

검색은 형태소 분석과 불용어를 처리하는 french 구성으로 Postgres 전체 텍스트 검색을 사용합니다. 이 데이터베이스에는 unaccent 확장이 설치되어 있지 않으므로 악센트를 접지 않습니다 — energie는 énergie와 일치하지 않습니다.

이를 해결하려면 Supabase SQL 편집기에서 한 번 실행하고 mcp-server.js의 FTS를 조정하세요:

CREATE EXTENSION IF NOT EXISTS unaccent;

1083개 행에서는 모든 쿼리가 빠른 순차 스캔이므로 아직 인덱스가 필요 없습니다. 코퍼스가 ~5만 행을 넘으면 to_tsvector 표현식에 GIN 인덱스를 추가하세요.

배포

현재 Render에서 운영 중입니다. 해당 서비스의 설정, 재배포 단계 및 플랫폼 특이 사항은 DEPLOYMENT.md 를 참조하세요.

호스트의 환경 설정에 DATABASE_URL — 그리고 이상적으로는 MCP_AUTH_TOKEN — 을 설정하세요. 커밋하지 마세요. .gitignore가 .env와 *.pem을 포함합니다.

서버는 0.0.0.0에 바인드하고 주입된 PORT를 존중합니다. 이는 컨테이너 플랫폼이 요구하는 방식입니다. 127.0.0.1에 바인드된 프로세스는 로그가 정상으로 보여도 컨테이너 외부에서 접근할 수 없습니다.

자체 도구 추가하기

mcp-server.js에서, 그리고 읽기 전용 헬퍼를 통해 쿼리를 라우팅하세요:

import { query } from "./db.js";

server.registerTool(
  "my_tool",
  {
    title: "My tool",
    description: "What it does — the model reads this to decide when to call it.",
    inputSchema: { term: z.string() },
  },
  async ({ term }) => {
    const rows = await query("SELECT id, title FROM news.articles WHERE title ILIKE $1", [`%${term}%`]);
    return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
  }
);

호출자 입력을 연결하여 SQL을 절대 만들지 말고, SQL을 인자로 받는 도구를 절대 추가하지 마세요 — 그러면 엔드포인트에 도달할 수 있는 사람에게 코퍼스의 읽기 표면을 넘겨주는 것이 됩니다.