mcpField
나
나라장터 사전규격

나라장터 사전규격

本地服务
github.com法律与政务015 周前更新

关于 나라장터 사전규격

这是将 data.go.kr 나라장터 预先规格信息 Open API 封装为本地 MCP 服务的工具,适合关注招标公告发布前规格公开阶段的采购人员和供应商。它提供按日期、机构、品目及组合条件检索的工具,并可查询规格意见与答复。

主要功能

  1. 01按日期或登记编号搜索预先规格
  2. 02按采购机构或需求机构筛选
  3. 03按品名和品目编号检索
  4. 04组合多项条件查询
  5. 05查看规格意见及答复

适用场景

  1. 01查找近期公开的预先规格
  2. 02跟踪特定机构的计划采购
  3. 03查找相关品目的规格公开信息
  4. 04查看某条规格的意见和回复

MCP 相关

本地 MCP 服务向 MCP 客户端提供五个只读工具,用于搜索预先规格、按机构或品目筛选、组合查询及获取规格意见。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"opendata-kr-narajangteo-prespec": {
"command": "npx",
"args": [
"-y",
"@opendata-kr/narajangteo-prespec-mcp"
],
"env": {
"DATA_GO_KR_SERVICE_KEY": "<DATA_GO_KR_SERVICE_KEY>",
"DATA_GO_KR_BASE_URL": "<DATA_GO_KR_BASE_URL>"
}
}
}
}
启动命令npx -y @opendata-kr/narajangteo-prespec-mcp
需要配置的环境变量
DATA_GO_KR_SERVICE_KEY密钥공공데이터포털 data.go.kr Decoding(원본) 인증키
DATA_GO_KR_BASE_URL서비스 경로를 포함한 전체 base URL 오버라이드

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npm@opendata-kr/narajangteo-prespec-mcp0.3.0

工具

5

收录的工具列表 · 更新于 3 周前

参数类型必填说明
kindarray否业务类别:cnstwk=工程,servc=服务,thng=货物,frgcpt=外国货物。未指定时会并行查询所有类别,消耗 4 次 API 请求。如果知道业务类别,请指定以节省认证密钥的每日流量。
pageinteger否页码(默认值:1)
endDatestring否查询结束日期 YYYYMMDD
dateTypeenum否日期范围依据:regist=登记日期时间(默认),change=变更日期时间regist | change
pageSizeinteger否每页条数(默认值:10)
startDatestring否查询开始日期 YYYYMMDD
specRegistNostring否按预先规格登记编号查询单条记录(指定时优先于日期范围)

详细介绍

@opendata-kr/narajangteo-prespec-mcp

나라장터 사전규격정보서비스(공공데이터포털 data.go.kr) Open API를 감싼 로컬 MCP 서버.

npm version CI node license

MCP 클라이언트에서 나라장터 사전규격(발주기관이 입찰공고 전에 규격서를 사전공개하고 의견을 받는 단계)을 자연어로 검색하고 조회한다. 예를 들어 이렇게 물어볼 수 있다.

  • "이번 달 올라온 물품 사전규격을 찾아줘"
  • "해군군수사령부가 발주한 사전규격을 검색해줘"
  • "사전규격등록번호 R26BD00234692의 규격서 의견을 보여줘"

특징

  • 20개 오퍼레이션을 5개 도구로 노출: 전체 조회/기관별/품목별/복합검색/규격서의견 유형별로 묶어 사용성을 단순화했다.
  • 4개 업무구분 병렬 검색: 공사/용역/물품/외자를 한 번에 조회한다. 업무구분 미지정 시 전 구분을 동시 검색한다.
  • 부분 실패 표면화: 일부 구분 조회가 실패해도 나머지 결과를 반환하고, 실패한 구분은 오류 메시지로 드러낸다(조용한 누락 없음).
  • data.go.kr 에러코드 한국어화: 인증키 만료, 트래픽 초과 등 결과코드를 조치 가능한 한국어 메시지로 정규화한다.
  • 이중 인코딩 방어: Encoding 키를 잘못 넣으면 경고하고, 요청은 한 번만 인코딩한다.
  • 타임아웃: API 호출에 타임아웃을 둔다.

준비물

  • Node.js 24 이상 (.nvmrc = lts/krypton).
  • data.go.kr 인증키:
    1. 공공데이터포털에서 나라장터 사전규격정보서비스를 활용신청해 [승인]을 받는다. 인증키는 계정당 하나지만, 각 API는 저마다 활용신청 승인이 있어야 그 API에서 인증된다. 서비스키가 있어도 이 API를 활용신청하지 않으면 인증 오류(코드 30)가 난다.
    2. 마이페이지 → 활용신청 현황 → 개발계정 상세에서 Decoding 서비스키를 복사한다.
    3. 같은 DATA_GO_KR_SERVICE_KEY는 같은 계정으로 활용신청한 다른 data.go.kr API에도 재사용된다.

提示

공공데이터포털이 처음이라면 활용신청부터 인증키 복사까지 그림으로 따라 하는 data.go.kr 인증키 발급 가이드를 참고한다.

서비스키는 반드시 Decoding(원본) 키를 넣는다. Encoding(%2B 등 포함) 키를 넣으면 이중 인코딩으로 인증 오류(코드 30)가 난다.

MCP 클라이언트 설정

MCP 클라이언트에 아래 config를 추가한다:

{
  "mcpServers": {
    "narajangteo-prespec": {
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

说明

@opendata-kr/narajangteo-prespec-mcp@latest를 쓰면 클라이언트가 항상 최신 버전을 받는다.

重要

DATA_GO_KR_SERVICE_KEY(필수, Decoding 원본 키)가 없으면 첫 호출이 인증 오류(코드 30)로 실패한다. 위 config의 env에 키를 넣는다. 원클릭 버튼이나 env를 config에 담지 못하는 클라이언트는 설치 후 셸 환경변수로 DATA_GO_KR_SERVICE_KEY를 설정한다.

클라이언트별 설정
Amp https://ampcode.com/manual#mcp 의 안내를 따르고 위 config를 사용한다. CLI로도 추가할 수 있다:
amp mcp add narajangteo-prespec -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest

이후 생성된 설정의 env(또는 셸 환경변수)에 DATA_GO_KR_SERVICE_KEY를 추가한다.

Antigravity

Antigravity 문서의 커스텀 MCP 서버 추가 방법을 따라 아래 config를 MCP servers 설정에 넣는다:

{
  "mcpServers": {
    "narajangteo-prespec": {
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}
Claude Code

Claude Code CLI로 서버를 추가한다 (가이드):

claude mcp add narajangteo-prespec --scope user --env DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest
Cline https://docs.cline.bot/mcp/configuring-mcp-servers 의 안내를 따르고 위 config를 사용한다.
Codex MCP 설정 가이드를 따르고 위 config를 사용한다. Codex CLI로도 추가할 수 있다:
codex mcp add narajangteo-prespec --env DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest

Windows

~/.codex/config.toml에 cmd /c 래핑으로 추가한다:

[mcp_servers.narajangteo-prespec]
command = "cmd"
args = ["/c", "npx", "-y", "@opendata-kr/narajangteo-prespec-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }
Command Code

Command Code CLI로 서버를 추가한다 (MCP 가이드):

cmd mcp add narajangteo-prespec --scope user npx -y @opendata-kr/narajangteo-prespec-mcp@latest

이후 생성된 설정의 env(또는 셸 환경변수)에 DATA_GO_KR_SERVICE_KEY를 추가한다.

Continue

Continue의 MCP 가이드를 따른다. Continue는 mcpServers를 배열로 쓴다:

{
  "mcpServers": [
    {
      "name": "narajangteo-prespec",
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  ]
}
Copilot CLI

Copilot CLI를 시작한다:

copilot

MCP 서버 추가 대화를 연다:

/mcp add

다음 필드를 입력하고 CTRL+S로 저장한다:

  • Server name: narajangteo-prespec
  • Server Type: [1] Local
  • Command: npx -y @opendata-kr/narajangteo-prespec-mcp@latest
  • Environment variables: DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키
Copilot / VS Code

버튼으로 설치:

在 VS Code 中安装

在 VS Code Insiders 中安装

按钮无法包含密钥。安装后,在 .vscode/mcp.json(或用户设置)的 env 中添加 DATA_GO_KR_SERVICE_KEY。

手动添加:

按照 VS Code MCP 配置指南操作,或使用 CLI。

macOS·Linux:

code --add-mcp '{"name":"narajangteo-prespec","command":"npx","args":["-y","@opendata-kr/narajangteo-prespec-mcp@latest"],"env":{"DATA_GO_KR_SERVICE_KEY":"발급받은_Decoding_키"}}'

Windows(PowerShell):

code --add-mcp '{"""name""":"""narajangteo-prespec""","""command""":"""npx""","""args""":["""-y""","""@opendata-kr/narajangteo-prespec-mcp@latest"""],"""env""":{"""DATA_GO_KR_SERVICE_KEY""":"""발급받은_Decoding_키"""}}'
Cursor

通过按钮安装:

将 narajangteo-prespec MCP 服务添加到 Cursor

按钮无法包含密钥。安装后,在 Cursor 的 MCP 设置中将 DATA_GO_KR_SERVICE_KEY 添加到 env。

手动添加:

在 Cursor Settings → MCP → New MCP Server 中使用上面的 config。

Factory CLI

使用 Factory CLI 添加服务(指南):

droid mcp add narajangteo-prespec "npx -y @opendata-kr/narajangteo-prespec-mcp@latest"

之后,在生成的设置中的 env(或 Shell 环境变量)中添加 DATA_GO_KR_SERVICE_KEY。

Gemini CLI

使用 Gemini CLI 添加服务。

项目范围:

gemini mcp add narajangteo-prespec npx -y @opendata-kr/narajangteo-prespec-mcp@latest

全局:

gemini mcp add -s user narajangteo-prespec npx -y @opendata-kr/narajangteo-prespec-mcp@latest

也可以按照 MCP 指南操作,并使用上面的 config。在 ~/.gemini/settings.json 中服务定义的 env 里添加 DATA_GO_KR_SERVICE_KEY。

Gemini Code Assist 按照 MCP 配置指南操作,并使用上面的 config。
Grok Build CLI
grok mcp add narajangteo-prespec npx -y @opendata-kr/narajangteo-prespec-mcp@latest

之后,在生成的设置中的 env(或 Shell 环境变量)中添加 DATA_GO_KR_SERVICE_KEY。更多选项请参阅文档。

JetBrains AI Assistant & Junie

在 Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add 中使用上面的 config。 Junie 也采用相同方式,在 Settings | Tools | Junie | MCP Settings → Add 中使用上面的 config。

Katalon Studio

Katalon StudioAssist 通过 MCP 代理连接 stdio 服务。

第 1 步: 按照MCP 代理设置指南安装代理。

第 2 步: 使用代理启动服务(在同一个 Shell 中导出 DATA_GO_KR_SERVICE_KEY):

DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest

第 3 步: 使用以下设置将服务添加到 StudioAssist:

  • 连接 URL: http://127.0.0.1:8080/mcp
  • 传输类型: HTTP
Kiro

在 Kiro Settings 中选择 Configure MCP → Open Workspace or User MCP Config,然后使用上面的 config。

或者,在 Activity Bar → Kiro → MCP Servers → Open MCP Config 中使用上面的 config。

Mistral Vibe

添加到 ~/.vibe/config.toml:

[[mcp_servers]]
name = "narajangteo-prespec"
transport = "stdio"
command = "npx"
args = ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }
OpenCode

添加到 opencode.json。如果文件不存在,则在 ~/.config/opencode/opencode.json 中创建(指南):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "narajangteo-prespec": {
      "type": "local",
      "command": ["npx", "-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
      "environment": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}
Qoder 在 **Qoder Settings** 中选择 `MCP Server` → `+ Add` → 使用上述 config。

或者,按照 MCP 指南操作,并使用上述 config。

Qoder CLI

使用 Qoder CLI 添加服务(指南):

项目范围:

qodercli mcp add narajangteo-prespec -- npx @opendata-kr/narajangteo-prespec-mcp@latest

全局:

qodercli mcp add -s user narajangteo-prespec -- npx @opendata-kr/narajangteo-prespec-mcp@latest

然后在生成的配置的 env(或 Shell 环境变量)中添加 DATA_GO_KR_SERVICE_KEY。

Visual Studio

通过按钮安装:

在 Visual Studio 中安装

按钮无法包含密钥。安装后,在服务配置的 env 中添加 DATA_GO_KR_SERVICE_KEY。

Warp

在 Settings | AI | Manage MCP Servers → + Add 中添加 MCP 服务,并使用上述 config。

Windsurf 按照 MCP 配置指南操作,并使用上述 config。Windsurf 使用 `mcpServers` 键(`~/.codeium/windsurf/mcp_config.json`)。
Zed

添加到 ~/.config/zed/settings.json(架构可能因 Zed 版本而异,请查阅 Zed 官方文档):

{
  "context_servers": {
    "narajangteo-prespec": {
      "command": { "path": "npx", "args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"] },
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}
ChatGPT · 仅限远程的客户端

像 ChatGPT Developer Mode 这样仅支持远程(HTTPS)MCP 的客户端无法直接连接本地 stdio 服务。使用 stdio→HTTP 桥接工具(mcp-proxy)将此服务作为 HTTP 服务运行,并通过公开的 HTTPS 端点(反向代理、隧道或托管服务)将其暴露,然后将该 URL 注册为连接器。

DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest

将 http://127.0.0.1:8080/mcp 暴露为公开 HTTPS 端点由用户自行负责。(mcp-remote 用于将 stdio 客户端连接到远程服务,因此不适用于此处。)

发现方式

此服务在 MCP 注册表中的标识为 io.github.opendata-kr/narajangteo-prespec-mcp。可以在支持 registry.modelcontextprotocol.io 的客户端中搜索并安装。

环境变量

环境变量必需保密默认值说明
DATA_GO_KR_SERVICE_KEY是是(无)公共数据门户的 **Decoding(原始)**认证密钥
DATA_GO_KR_BASE_URL否否https://apis.data.go.kr/1230000/ao/HrcspSsstndrdInfoService包含服务路径的完整 URL 覆盖值

工具

全部 5 个工具都用于只读查询。20 个操作按查询方式分组。以下参数适用于所有工具。

  • kind:string[]。业务类型数组:cnstwk(工程)servc(服务)thng(物品)frgcpt(外资)。未指定时并行查询所有类型。并行查询会消耗 4 次 API 请求,因此已知业务类型时请指定
  • page:number。页码(默认值为 1)
  • pageSize:number。每页条数(默认值为 10,最大值为 100)
search_prespecs

按日期范围(登记/变更日期时间)或事前规格登记编号查询事前规格。用于简单的日期范围或编号查询。

参数类型说明
startDatestring查询开始日期 YYYYMMDD
endDatestring查询结束日期 YYYYMMDD
dateTypestring日期范围依据:regist(登记日期时间,默认值)change(变更日期时间)
specRegistNostring按事前规格登记编号查询单条记录(指定时优先于日期范围)
search_prespecs_by_institution

按订购机构名称或实际需求机构名称查询事前规格。用于查看特定机构计划订购的项目。

参数类型说明
orderInstitutionstring订购机构名称
demandInstitutionstring实际需求机构名称
startDatestring查询开始日期 YYYYMMDD
endDatestring查询结束日期 YYYYMMDD
search_prespecs_by_product

按商品名称或详细商品名称(编号)查询事前规格。用于查找关注商品的事前规格。

参数类型说明
productNamestring商品名称(项目名称)
detailProductCodestring详细商品名称编号
detailProductNamestring详细商品名称
startDatestring查询开始日期 YYYYMMDD
endDatestring查询结束日期 YYYYMMDD
search_prespecs_advanced

발주기관·수요기관·품명·참조번호·SW사업여부 등 복합 조건으로 사전규격을 조회한다. 여러 필터를 동시에 걸 때 쓴다.

파라미터타입설명
startDatestring접수 시작일 YYYYMMDD
endDatestring접수 종료일 YYYYMMDD
specRegistNostring사전규격등록번호로 조회(지정 시 최우선)
refNostring참조번호로 조회(지정 시 기간보다 우선)
noticeInstitutionstring발주기관명
demandInstitutionstring수요기관명
productNamestring품명(사업명)
detailProductCodestring세부품명번호
swBusinessYnstringSW사업 여부(Y/N)

조회 우선순위는 사전규격등록번호 > 참조번호 > 접수일시 순이다. 세부품명(detailProductName) 검색은 이 API가 지원하지 않는다. 세부품명으로 찾으려면 search_prespecs_by_product를 쓴다.

get_prespec_opinions

특정 사전규격(사전규격등록번호)에 달린 규격서 의견·답변 목록을 조회한다.

파라미터타입설명
specRegistNostring사전규격등록번호
startDatestring조회 시작일 YYYYMMDD
endDatestring조회 종료일 YYYYMMDD

모든 도구의 반환은 { query, results }다. results는 업무구분별로 { totalCount, invalidCount, items }를, 실패 시 해당 구분에 { error }를 담는다. invalidCount는 응답 스키마 검증에서 탈락해 items에서 제외된 건수다. 0이 아니면 API 응답 필드가 예고 없이 바뀐 신호이므로 이슈로 알려주면 반영한다.

응답 필드

Prespec (①②③④ 공통)

specRegistNo(사전규격등록번호), productName(품명/사업명), assignedBudget(배정예산액), orderInstitution(발주기관), demandInstitution(실수요기관), registDt(등록일시), changeDt(변경일시), opinionCloseDt(의견등록마감), receiptDt(접수일시), refNo(참조번호), bidNoticeList(관련 입찰공고번호 목록), businessDivision(업무구분), deliveryDays(납품기한일수), deliveryDeadline(납품기한), officialName(담당자), officialTel(담당자 전화), swBusinessYn(SW사업 여부), productDetailList(세부품목 배열: itemSeq·detailProductNo·detailProductName. 공사·용역은 빈 배열).

PrespecOpinion (⑤)

specRegistNo, refNo, opinionNo(의견번호), replyNo(답변번호), opinionTitle(제목), opinionContent(내용), writerCorp(작성업체), writerName(작성자), inputDt(등록일시), writerTel, writerEmail, opinionFileUrls(첨부파일 URL 배열).

개발

nvm use            # Node 24
pnpm install
pnpm test          # vitest
pnpm typecheck     # tsc --noEmit
pnpm build         # tsup, dist/ 생성

문제 해결

  • 인증 오류(코드 30): Encoding 키를 넣으면 이중 인코딩으로 실패한다. Decoding(원본) 키를 쓴다. 서버가 시작 시 Encoding 키로 보이면 경고 로그를 남긴다.

  • 결과코드 메시지: 트래픽 초과, 인증키 만료 등 data.go.kr 결과코드는 한국어 메시지로 정규화되어 반환된다.

  • 도구 동작 점검: MCP inspector로 직접 호출해 볼 수 있다.

    npx @modelcontextprotocol/inspector npx -y @opendata-kr/narajangteo-prespec-mcp
    

라이선스

MIT

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。