Skip to main content
Glama
yeremu-rgb

theminjoo-mcp

by yeremu-rgb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

theminjoo-api-mcp

더불어민주당 공식 홈페이지의 공개 게시물 중 **논평·브리핑(brd=11)**과 **모두발언(brd=230)**을 읽어 REST API와 MCP(Model Context Protocol)로 제공하는 비공식 오픈소스 프로젝트입니다.

이 프로젝트는 더불어민주당의 공식 프로젝트가 아닙니다. 원문 저작권과 이용 조건은 원 출처에 따르며, 운영 시 원 사이트에 과도한 요청을 보내지 않도록 캐시와 적절한 호출 간격을 사용하세요.

원본 데이터

Related MCP server: AssemblyMCP

기능

  • brd=11: 논평·브리핑 목록/본문

  • brd=230: 모두발언 목록/본문

  • FastAPI REST API + OpenAPI

  • 원격 MCP(Streamable HTTP): /mcp

  • 로컬 MCP(stdio): theminjoo-mcp

  • MCP tools: list_posts, get_post, search_posts

  • 선택적 Bearer Token 인증

  • CORS/MCP 헤더 지원

  • 5분 기본 TTL 캐시

  • pytest, Ruff, Docker, GitHub Actions CI

  • Render 배포 Blueprint

설치

git clone https://github.com/yeremu-rgb/theminjoo-api-mcp.git
cd theminjoo-api-mcp
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e '.[dev]'

REST API + 원격 MCP 실행

theminjoo-api

기본 주소:

  • REST: http://localhost:8000

  • Swagger: http://localhost:8000/docs

  • MCP Streamable HTTP: http://localhost:8000/mcp

  • Health check: http://localhost:8000/health

배포 플랫폼에서 PORT 환경변수를 제공하면 자동으로 해당 포트를 사용합니다.

REST 엔드포인트

GET /health
GET /v1/boards
GET /v1/posts?board=11&offset=0&limit=20
GET /v1/posts?board=230&offset=0&limit=20
GET /v1/posts/{board}/{post_id}
GET /v1/search?board=11&q=키워드&pages=3

원격 MCP

원격 MCP는 같은 FastAPI 프로세스의 /mcp에 Streamable HTTP로 마운트됩니다.

MCP tools

  • list_posts(board, offset=0, limit=20)

  • get_post(board, post_id)

  • search_posts(board, query, pages=3)

board 값:

  • 11: 논평·브리핑

  • 230: 모두발언

Bearer Token 보호

공개 인터넷에 배포할 때 토큰 인증을 켜려면:

export THEMINJOO_MCP_TOKEN='change-me-to-a-long-random-secret'
theminjoo-api

MCP 요청에는 다음 헤더를 보냅니다.

Authorization: Bearer change-me-to-a-long-random-secret

토큰을 설정하지 않으면 /mcp는 인증 없이 접근할 수 있습니다. REST API는 이 토큰과 무관하게 공개됩니다.

로컬 stdio MCP

theminjoo-mcp

stdio MCP 클라이언트 예시:

{
  "mcpServers": {
    "theminjoo": {
      "command": "theminjoo-mcp"
    }
  }
}

Docker

docker build -t theminjoo-api-mcp .
docker run --rm -p 8000:8000 theminjoo-api-mcp

토큰을 적용하려면:

docker run --rm -p 8000:8000 \
  -e THEMINJOO_MCP_TOKEN='change-me' \
  theminjoo-api-mcp

또는:

docker compose up --build

Render 배포

저장소 루트의 render.yaml을 사용해 Render Blueprint로 배포할 수 있습니다.

  1. Render에서 New → Blueprint

  2. GitHub 저장소 yeremu-rgb/theminjoo-api-mcp 선택

  3. 배포

  4. 배포 URL이 https://YOUR-SERVICE.onrender.com이라면 MCP URL은: https://YOUR-SERVICE.onrender.com/mcp

  5. 필요한 경우 Render 환경변수에 THEMINJOO_MCP_TOKEN 추가

ChatGPT에 연결할 때

ChatGPT는 로컬 stdio 서버가 아니라 인터넷에서 접근 가능한 원격 MCP URL이 필요합니다. 따라서 먼저 Render 등 HTTPS 호스팅에 배포한 다음 배포된 /mcp URL을 ChatGPT의 커스텀 MCP/App 설정에 등록합니다.

예시:

https://YOUR-SERVICE.onrender.com/mcp

토큰 인증을 켠 경우 연결 설정에도 동일한 Bearer Token을 입력합니다.

Claude / ChatGPT OAuth 연결

원격 MCP /mcp는 MCP Authorization 규격에 맞춘 OAuth 2.1 호환 흐름을 제공합니다.

지원 엔드포인트:

GET  /.well-known/oauth-protected-resource
GET  /.well-known/oauth-protected-resource/mcp
GET  /.well-known/oauth-authorization-server
POST /oauth/register
GET  /oauth/authorize
POST /oauth/authorize
POST /oauth/token

지원 기능:

  • OAuth Authorization Code

  • PKCE S256

  • Dynamic Client Registration(DCR)

  • Bearer access token

  • offline_access + refresh token

  • MCP 401 WWW-Authenticate: resource_metadata=... discovery

Claude

커스텀 커넥터 URL:

https://theminjoo-api-mcp-production.up.railway.app/mcp

자동 등록이 실패해 OAuth Client ID를 수동 입력하라는 UI가 나오면 다음 public client ID를 사용할 수 있습니다.

theminjoo-claude

Client Secret은 비워 둡니다. 연결 과정에서 브라우저에 승인 화면이 열리면 연결 허용을 선택합니다.

ChatGPT

지원되는 ChatGPT Developer Mode / Custom MCP App 환경에서는 동일한 URL을 사용합니다.

https://theminjoo-api-mcp-production.up.railway.app/mcp

OAuth Client ID를 수동으로 요구하는 경우:

theminjoo-chatgpt

Client Secret은 비워 둡니다. 서버는 offline_access와 refresh token을 광고하고 발급하므로 장기 연결 갱신을 지원합니다.

OAuth는 이 프로젝트의 공개 데이터 MCP 연결을 승인하기 위한 호환 계층입니다. 별도의 민주당 계정이나 사용자 신원을 인증하지 않습니다.

환경변수

.env.example 참고:

THEMINJOO_BASE_URL=https://theminjoo.kr/main/sub/news
THEMINJOO_REQUEST_TIMEOUT=15
THEMINJOO_CACHE_TTL_SECONDS=300
THEMINJOO_DEFAULT_PAGE_SIZE=20
THEMINJOO_MAX_PAGE_SIZE=100
THEMINJOO_MCP_TOKEN=
THEMINJOO_CORS_ORIGINS=*

테스트

pip install -e '.[dev]'
ruff check .
pytest -q
python -m build

fixture 기반 테스트는 외부 사이트 장애와 무관하게 파서/API 기본 동작을 검증합니다.

프로젝트 구조

src/theminjoo_api_mcp/
  api.py           # REST + /mcp mount
  client.py
  parser.py
  mcp_server.py    # MCP tools + stdio/HTTP 공용 FastMCP
  models.py
  config.py
tests/
  fixtures/
.github/workflows/ci.yml
Dockerfile
render.yaml
.env.example

License

MIT. 단, 수집 대상 원문 콘텐츠의 권리는 해당 원문 권리자에게 있습니다.

Available Tools

3 tools
get_postB

Get one official post including body text and metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYes
post_idYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. 'Get' implies a read-only operation, and the description usefully states the returned content includes body text and metadata. However, it does not clarify behavior for missing posts, permission requirements, or what 'official' means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no redundant filler. It efficiently communicates the core action and output, though the word 'official' introduces slight ambiguity that could have been clarified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter getter, the description is serviceable, but with no output schema and no annotations it leaves out return-value structure, error behavior, and explicit alternative routing. The core information is present, yet several operational details are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it does not explain the role of board or post_id beyond the schema's bare titles. The phrase 'body text and metadata' concerns the return value, not the parameters' meaning or relationships.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('one official post') and indicates the content returned ('body text and metadata'). It implicitly distinguishes from list_posts and search_posts by focusing on a single post, though it does not explicitly name or contrast the siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for fetching a single known post, especially given the required board and post_id parameters, but it provides no explicit guidance on when to choose it over list_posts or search_posts. No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_postsB

List official 더불어민주당 posts. board: 11=논평·브리핑, 230=모두발언.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYes
limitNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral transparency burden. It does disclose the 'official' scope and the board categories, which is useful, and 'List' implies a read operation. However, it does not mention authentication needs, rate limits, pagination behavior beyond the schema defaults, or any other behavioral traits. This is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loads the core action before the board mapping. Every sentence earns its place, and the format is easy to scan. It is concise rather than under-specified, though it could have included one more sentence of usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, the presence of an output schema, and the explicit board mapping, the description is mostly sufficient for an agent to issue a correct call. It lacks usage guidance versus siblings and omits any behavioral details such as authentication or pagination semantics, but nothing critical is entirely missing for a simple list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does add value for the required 'board' parameter by enumerating meaningful values (11=논평·브리핑, 230=모두발언). The 'limit' and 'offset' parameters are not described, but they are standard pagination fields with defaults in the schema, so an agent can infer their semantics. Partial compensation for a low-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('official 더불어민주당 posts'), which makes the basic purpose unambiguous. It also maps board IDs to post categories, adding specificity. However, it does not explicitly distinguish itself from the sibling tools search_posts and get_post, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to use this tool versus search_posts or get_post. The description provides board semantics but never states exclusions, prerequisites, or conditions under which the agent should prefer one sibling over another.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_postsB

Search recent post titles across up to 10 list pages.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYes
pagesNo
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It does disclose meaningful behavioral constraints: search is limited to titles, recency, and a maximum of 10 list pages. However, it does not explain ordering, matching behavior, how 'recent' is determined, or what happens at page limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word adds scope or constraint information, making it appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although the tool has a simple flat schema and an output schema, the description lacks essential context about the required 'board' parameter and the meaning of 'list pages.' With no annotations and zero schema description coverage, the description is not complete enough for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It partially clarifies 'query' (searches post titles) and 'pages' (up to 10 list pages), but it never explains the 'board' parameter, which is required. This leaves a meaningful semantic gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search), the resource (post titles), and a scoping constraint (recent, up to 10 list pages). It is distinct enough from the siblings, though 'list pages' is slightly ambiguous and does not explicitly contrast with list_posts or get_post.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus list_posts or get_post. There are no explicit conditions, exclusions, or alternatives, so the agent must infer the intended use context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.3.0
    • First observedget_post
    • First observedlist_posts
    • First observedsearch_posts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear, distinct role: list_posts returns posts from a specific board, get_post retrieves a single full post, and search_posts finds posts by title across recent pages. There is no meaningful overlap that would confuse an agent.

Naming Consistency5/5

All tool names follow the same verb_noun pattern (list_posts, get_post, search_posts) with consistent snake_case. The naming is predictable and standard.

Tool Count4/5

Three tools is slightly minimal but appropriate for a read-only content retrieval server focused on official party posts. Each tool serves a distinct retrieval need without redundancy.

Completeness4/5

For a read-only posting board domain, list/get/search covers the essential lifecycle of content discovery and retrieval. Minor additions like category filtering or pagination details could be nice, but the core surface is sufficient and has no dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • open-assembly-mcp

    kyusik-yang
    A
    license
    A
    quality
    D
    maintenance
    MCP server for the Korean National Assembly Open API, enabling querying of bills, members, votes, committees, and more via natural language.
    20
    Apache 2.0

  • AssemblyMCP

    StatPan
    A
    license
    B
    quality
    D
    maintenance
    Enables LLM clients to search and analyze bills, members, committees, meetings, votes, and reports from the South Korean National Assembly OpenAPI through MCP tools.
    26
    MIT

  • Korean Bill & Debate MCP

    epoko77-ai
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables exploration of Korean National Assembly data by connecting bills, committee reviews, and official records. Allows users to ask natural language questions and receive structured answers with citations to original documents.
    26
    Apache 2.0