MCP server yeteneklerinin statik anlık görüntülerini tanımlamak, doğrulamak ve paylaşmak için TypeScript tipleri ve JSON Schema sağlar.
Ayrıca bilinen adı sourcey/mcp-schema
- Yıldızlar
- 2
- Araçlar
- —
- İndirmeler, 30 gün
- —
- En son sürüm
- —
- Son commit
- 9 Kas 2026
- Lisans
- MIT
schema MCP nedir?
MCP server yeteneklerinin statik anlık görüntülerini tanımlamak, doğrulamak ve paylaşmak için TypeScript tipleri ve JSON Schema sağlar.
Özet, projenin README dosyasından oluşturuldu
schema MCP sunucusu hakkında
Model Context Protocol sunucuları inşa eden veya yöneten geliştiriciler, sunucu yeteneklerinin statik anlık görüntülerini tanımlamak, doğrulamak ve paylaşmak için bu paketi kullanabilirler. OpenAPI'ye benzer şekilde, bir sunucunun araçlarını, kaynaklarını, istemlerini ve bağlantı ipuçlarını versiyonlanabilir bir dosya formatında temsil etmek için TypeScript tipleri ve JSON Schema sunar. Bu, sunucuyla canlı bir bağlantıya ihtiyaç duymadan dokümantasyon ve kod üretimi yapılmasına olanak tanır.
Paket iki ana belge türünü destekler: McpSpec kullanarak sunucu anlık görüntüleri ve AgentPluginsMcpConfig kullanarak Agent Plugins yapılandırması. stdio, streamable-http ve kullanımdan kaldırılan sse dahil olmak üzere çeşitli taşıma türlerini destekler. Kullanıcılar, yapılandırma dosyalarının resmi spesifikasyonlara uygun olduğundan emin olmak için bu şemaları Ajv gibi standart JSON Schema doğrulayıcılarını kullanarak mevcut iş akışlarına entegre edebilirler. Şema, protokol revizyonlarını tarih dizeleri olarak doğruladığı için temel protokol evrim geçirse bile uyumluluğunu korur.
Neler yapabilirsiniz
- 1Sunucu yetenek anlık görüntülerini doğrulayınStatik bir JSON dosyasının bir sunucunun araçlarını ve kaynaklarını bir JSON Schema doğrulayıcısı kullanarak doğru şekilde tanımlayıp tanımlamadığını kontrol edin.
- 2Agent plugin bağlantılarını yapılandırınBir agent plugin yapılandırma dosyası için isimlendirilmiş sunucu bağlantıları tanımlayın.
- 3Tip güvenli sunucu spesifikasyonları oluşturunAraçlar ve kaynaklar için tam tip güvenliğine sahip bir TypeScript sunucu spesifikasyon nesnesi oluşturun.
- 4Sunucu arayüzlerini dokümante edinDokümantasyon amacıyla bir sunucunun yüzey alanını paylaşılabilir bir dosyada kaydedin.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
schema MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleschema MCP'yi Claude Code içine yükleyin
$ claude mcp add mcp-schema -- npx -y mcp-schemaschema MCP'yi Cursor içine yükleyin
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}schema MCP'yi VS Code içine yükleyin
.vscode/mcp.json
{
"servers": {
"mcp-schema": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}schema MCP'yi VS Code CLI içine yükleyin
$ code --add-mcp '{"name":"mcp-schema","type":"stdio","command":"npx","args":["-y","mcp-schema"]}'schema MCP'yi Claude Desktop içine yükleyin
claude_desktop_config.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}schema MCP'yi Codex içine yükleyin
$ codex mcp add mcp-schema -- npx -y mcp-schemaschema MCP'yi Codex config.toml içine yükleyin
~/.codex/config.toml
[mcp_servers.mcp-schema] command = "npx" args = ["-y", "mcp-schema"]
schema MCP'yi Gemini CLI içine yükleyin
$ gemini mcp add -s user mcp-schema npx -- -y mcp-schemaschema MCP'yi Gemini settings.json içine yükleyin
~/.gemini/settings.json
{
"mcpServers": {
"mcp-schema": {
"command": "npx",
"args": [
"-y",
"mcp-schema"
]
}
}
}Otomatik kontroller
Çalıştırıldı 14 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır
- Kaynak deposu bağlantılı ve erişilebilirsourcey/mcp-schema is public and reachablegithub.com/sourcey/mcp-schema ↗Geçti
- Paket, bu depoyu kaynağı olarak gösteriyormcp-schema names sourcey/mcp-schema as sourcenpmjs.com/package/mcp-schema ↗Geçti
- Derleme kökeni (Sigstore onayı)Sigstore attestation for mcp-schemanpmjs.com/package/mcp-schema/v/0.3.3#provenance ↗Geçti
- Açık kaynak lisansı (OSI)MITspdx.org/licenses/MIT.html ↗Geçti
- Son bir yıl içinde commit veya sürüm mevcutLast commit or release 2026-11-09github.com/sourcey/mcp-schema ↗Geçti
- OpenSSF ScorecardKontrol edilmedi
- Paket adı popüler bir pakete yakın değilNo popular package one edit away from mcp-schemaGeçti
- Pakette veya bağımlılıklarında kritik uyarı yokKontrol edilmedi
- Modele yönelik gizli talimat yok0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersGeçti
- Yıkıcı araçlar etiketlenmişKontrol edilmedi
- Uzak uç nokta MCP el sıkışmasına yanıt veriyorKontrol edilmedi
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 soruları
schema MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde claude mcp add mcp-schema -- npx -y mcp-schema komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
schema MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
MCP spec (mcp.json) nedir?
MCP spec, bir MCP server'ın araçlarını, kaynaklarını ve istemlerini (prompts) içeren, API'ler için openapi.json'ın işlevine benzer şekilde oluşturulmuş statik bir yetenek anlık görüntüsüdür.
Bu paket çalışma zamanında şemaları indirir mi?
Hayır, resmi şema paketin içine yerel olarak dahil edilmiştir.