MCP server의 기능을 정의, 검증 및 공유할 수 있는 정적 스냅샷을 위한 TypeScript 타입과 JSON Schema를 제공합니다.
다른 이름 sourcey/mcp-schema
- 스타
- 2
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 9일
- 라이선스
- MIT
schema MCP란?
MCP server의 기능을 정의, 검증 및 공유할 수 있는 정적 스냅샷을 위한 TypeScript 타입과 JSON Schema를 제공합니다.
프로젝트 README에서 생성된 요약
schema MCP server 정보
Model Context Protocol server를 구축하거나 관리하는 개발자는 이 패키지를 사용하여 server 기능의 정적 스냅샷을 정의, 검증 및 공유할 수 있습니다. OpenAPI와 유사한 버전 관리 가능 파일 형식을 통해 server의 tools, resources, prompts 및 connection hints를 표현할 수 있는 TypeScript 타입과 JSON Schema를 제공합니다. 이를 통해 server에 대한 실시간 연결 없이도 문서화 및 코드 생성이 가능합니다.
이 패키지는 두 가지 주요 문서 유형을 지원합니다. McpSpec을 사용하는 server snapshot과 AgentPluginsMcpConfig를 사용하는 Agent Plugins 설정입니다. stdio, streamable-http 및 지원이 중단된 sse를 포함한 다양한 전송 유형을 처리합니다. 사용자는 Ajv와 같은 표준 JSON Schema 검증기를 사용하여 기존 워크플로우에 이러한 스키마를 통합하고 설정 파일이 공식 사양을 준수하는지 확인할 수 있습니다. 스키마가 프로토콜 버전을 날짜 문자열로 검증하므로 기반 프로토콜이 진화하더라도 호환성을 유지합니다.
활용 사례
- 1server 기능 스냅샷 검증JSON Schema 검증기를 사용하여 정적 JSON 파일이 server의 tools 및 resources를 올바르게 설명하는지 확인합니다.
- 2agent plugin 연결 설정agent plugin 설정 파일을 위한 이름 지정된 server 연결을 정의합니다.
- 3타입 안정성이 보장된 server 사양 생성tools 및 resources에 대해 완전한 타입 안정성을 갖춘 TypeScript server specification 객체를 생성합니다.
- 4server 인터페이스 문서화문서화 목적으로 server의 인터페이스 범위를 공유 가능한 파일로 캡처합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
schema MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 schema MCP 설치
$ claude mcp add mcp-schema -- npx -y mcp-schemaCursor에 schema MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}VS Code에 schema MCP 설치
.vscode/mcp.json
{
"servers": {
"mcp-schema": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}VS Code CLI에 schema MCP 설치
$ code --add-mcp '{"name":"mcp-schema","type":"stdio","command":"npx","args":["-y","mcp-schema"]}'Claude Desktop에 schema MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}Codex에 schema MCP 설치
$ codex mcp add mcp-schema -- npx -y mcp-schemaCodex config.toml에 schema MCP 설치
~/.codex/config.toml
[mcp_servers.mcp-schema] command = "npx" args = ["-y", "mcp-schema"]
Gemini CLI에 schema MCP 설치
$ gemini mcp add -s user mcp-schema npx -- -y mcp-schemaGemini settings.json에 schema MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능sourcey/mcp-schema is public and reachablegithub.com/sourcey/mcp-schema ↗통과
- 패키지가 이 저장소를 소스로 명시mcp-schema names sourcey/mcp-schema as sourcenpmjs.com/package/mcp-schema ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for mcp-schemanpmjs.com/package/mcp-schema/v/0.3.3#provenance ↗통과
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-09github.com/sourcey/mcp-schema ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from mcp-schema통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기mcp-schema
TypeScript types and JSON Schema for Model Context Protocol server specifications.
Define, validate, and share static snapshots of MCP servers.
Agent Plugins configuration and server snapshots
This package describes two distinct documents:
| Contract | Exports | Purpose |
|---|---|---|
| Server snapshot | McpSpec, mcpSpecSchema |
A server's tools, resources, prompts, and connection hints |
| Agent Plugins 1.0.0 MCP configuration | AgentPluginsMcpConfig, AgentPluginsMcpServer, agentPluginsMcpSchema |
A plugin's named server connections in root mcp.json |
Both have been called mcp.json. Use a filename such as api.snapshot.json for
snapshots when working with an Agent Plugin. The standard plugin configuration
requires $schema and mcpServers; it does not contain introspection results.
import { agentPluginsMcpSchema, AGENT_PLUGINS_MCP_SCHEMA_URL } from "mcp-schema/agent-plugins";
import type { AgentPluginsMcpConfig } from "mcp-schema/agent-plugins";
import { Ajv2020 } from "ajv/dist/2020.js";
const config: AgentPluginsMcpConfig = {
$schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
mcpServers: {
api: { type: "streamable-http", url: "https://example.com/mcp" },
local: { type: "stdio", command: "./bin/server", cwd: "${PLUGIN_ROOT}" },
},
};
const validate = new Ajv2020().compile(agentPluginsMcpSchema);
console.log(validate(config), AGENT_PLUGINS_MCP_SCHEMA_URL);
These exports are also available from the main entrypoint. The official schema
is bundled locally, and its TypeScript types are generated from those exact
schema bytes. It is a closed union of stdio, streamable-http, and legacy
sse. The normative specification additionally defines URL/header semantics,
filesystem containment, variable expansion, and failure boundaries that a JSON
Schema alone cannot enforce. mcp-parser
implements those configuration checks and named-server snapshotting.
Maintaining the upstream contract
The published canonical schema
is the authority in src/agent-plugins/mcp.schema.json. Its generated runtime
export and types must pass npm run check:agent-plugins in CI. Run
npm run check:agent-plugins -- --upstream to compare with the canonical online
schema and detect a newer release on the published specification page. The
Agent Plugins upstream workflow runs that check every Monday at 03:17 UTC and
can also be dispatched manually. A new release or schema change fails the check
for review. After adopting a published specification release, review its normative
semantic changes in mcp-parser, update the canonical bytes, regenerate with
npm run generate:agent-plugins, and test both packages together. A working
draft is not automatically a supported release. No schema is downloaded at
runtime. Agent Plugins schema material is Apache-2.0 licensed; its license and
attribution are distributed with the package.
What the snapshot describes
An mcp.json document is a static description of an MCP server's surface, not a
wire protocol. This package is therefore revision-independent: it records which
protocol revision a snapshot came from without being tied to any one of them.
mcpVersion holds the revision the server answered with, and mcpVersions holds
the set it reports it supports. Both are validated as YYYY-MM-DD shapes rather
than against a list of known revisions, so a document produced against a
revision newer than this package still validates.
Types cover tools (with inputSchema, outputSchema, and
annotations),
resources, resource templates, prompts, icons, server capabilities, and all three
transports (stdio, Streamable HTTP, and the specification-deprecated HTTP+SSE).
Deliberately out of scope: JSON-RPC envelopes, content types, sessions, and the
client features the specification deprecated in
2026-07-28
(roots, sampling, logging). A snapshot describes what a server offers, not a
conversation with it.
Install
npm install mcp-schema
Usage
TypeScript types
import type { McpSpec, McpTool, McpResource } from "mcp-schema";
const spec: McpSpec = {
mcpSpec: "0.3.1",
mcpVersion: "2025-11-25",
server: { name: "weather-server", version: "1.0.0" },
description: "Real-time weather data for any city.",
tools: [
{
name: "get_weather",
description: "Get current weather for a location",
inputSchema: {
type: "object",
properties: {
city: { type: "string", description: "City name" },
},
required: ["city"],
},
outputSchema: {
type: "object",
properties: {
temperature: { type: "number" },
conditions: { type: "string" },
},
},
annotations: { readOnlyHint: true },
},
],
resources: [
{
uri: "weather://cities",
name: "Supported Cities",
description: "List of cities with weather data",
mimeType: "application/json",
},
],
};
JSON Schema validation
import { mcpSpecSchema } from "mcp-schema/schema";
// Use with any JSON Schema validator
import Ajv from "ajv";
const ajv = new Ajv();
const validate = ajv.compile(mcpSpecSchema);
const valid = validate(spec);
if (!valid) {
console.error(validate.errors);
}
What is mcp.json?
An MCP spec (mcp.json) is a static snapshot of an MCP server's capabilities; its tools, resources, and prompts. Think of it as openapi.json for MCP servers.
MCP servers describe themselves at runtime via tools/list, resources/list, and prompts/list. An MCP spec captures that information in a versionable, shareable file that can be used for documentation, validation, and code generation.
mcp.json Format
The root document:
| Field | Type | Required | Description |
|---|---|---|---|
mcpSpec |
string |
yes | Format version (semver) |
mcpVersion |
string |
no | Protocol revision the server answered with, YYYY-MM-DD |
mcpVersions |
string[] |
no | Every protocol revision the server reports it supports |
server |
object |
yes | Server name and version |
description |
string |
no | Extended description (markdown) |
capabilities |
object |
no | Declared server capabilities |
transport |
object |
no | Transport config hints |
tools |
McpTool[] |
no | Tools the server exposes |
resources |
McpResource[] |
no | Concrete resources |
resourceTemplates |
McpResourceTemplate[] |
no | Parameterized resource templates |
prompts |
McpPrompt[] |
no | Prompt templates |
$defs |
object |
no | Shared schema definitions |
Tools
{
"name": "search_docs",
"description": "Search documentation by query",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "number", "default": 10 }
},
"required": ["query"]
},
"outputSchema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": { "type": "string" },
"url": { "type": "string" }
}
}
}
}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true
}
}
Resources
{
"uri": "docs://index",
"name": "Documentation Index",
"description": "Top-level index of all documentation pages",
"mimeType": "application/json"
}
Resource Templates
{
"uriTemplate": "docs://pages/{slug}",
"name": "Documentation Page",
"description": "A single documentation page by slug",
"mimeType": "text/markdown"
}
Prompts
{
"name": "summarize_page",
"description": "Summarize a documentation page",
"arguments": [
{ "name": "url", "description": "Page URL to summarize", "required": true },
{ "name": "style", "description": "Summary style (brief, detailed)", "required": false }
]
}
MCP Specification Resources
- MCP Specification (current revision)
- Specification repo (includes JSON Schema for each protocol version)
- TypeScript SDK (
@modelcontextprotocol/sdk) - Python SDK (
mcpon PyPI)
Related
- mcp-parser: snapshot live MCP servers, parse and validate
mcp.json, and generate markdown/docs outputs - sourcey: generate documentation from MCP specs, OpenAPI, and markdown
License
MIT
schema MCP 질문
schema MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add mcp-schema -- npx -y mcp-schema를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
schema MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
MCP spec (mcp.json)이란 무엇인가요?
MCP spec은 API의 openapi.json과 유사하게 MCP server의 도구(tools), 리소스(resources), 프롬프트(prompts)를 포함한 기능을 정적으로 기록한 스냅샷입니다.
이 패키지는 런타임에 스키마를 다운로드하나요?
아니요, 공식 스키마는 패키지 내에 로컬로 포함되어 있습니다.