Skills Guide

Resource-Oriented API Design for MCP

VerifiedCaution

Provides resource-oriented API design patterns for MCP, covering URI scheme design, resource model definition, provider implementation, caching strategies, and resource transformation patterns.

Download and use
Sby Skills Guide Bot
DevelopmentIntermediate
3/4/2026
Claude CodeCursorCodex
#mcp#api-design#uri-scheme#resource-provider#rest

Recommended for

Backend developerClaude CodeCode reviewFrontend developerCursorFullstack developer

Automated summary

A skill that guides the design and implementation of resource-oriented APIs for MCP, from resource modeling and URI scheme design through to writing the provider.

Strengths

  • Clear three-phase workflow: resource modeling, provider implementation, then optimization and verification
  • Ships concrete artifacts — a JSON resource-definition template and a TypeScript provider skeleton — plus validation scripts for definitions and URIs
  • Actionable best-practice list: hierarchical verb-free URIs, plural kebab-case names, path depth capped at four levels, proper percent-encoding
  • Covers security checks (path traversal, scheme allowlisting) and includes dedicated references on caching and resource transformation

Limitations

  • Written entirely in Japanese, which restricts use by non-Japanese-speaking teams
  • Scoped strictly to MCP resources; tools, prompts and other primitives are not addressed
  • Assumes a TypeScript/Node toolchain and the presence of agents/, references/, scripts/ and assets/ folders beside SKILL.md
When to use it

Use it when designing an MCP resource model or URI scheme, or when implementing a resource provider.

When not to use it

Skip it when designing MCP tools or prompts, or for a plain REST API unrelated to MCP.

Security analysis

Caution
Quality score82/100

No destructive, exfiltration, obfuscation, or safety-disabling instructions are present, and the described tool use is legitimate for API design and validation. However, Bash plus Write/Edit and referenced local scripts provide meaningful execution and filesystem-modification capability, so it warrants caution rather than safe.

Findings
  • •Declares Bash tool, allowing command execution for validation/logging workflows.
  • •Declares Write/Edit tools, allowing modification of project files.
  • •References local scripts (validate-resource-definition.mjs, validate-uri.mjs, log_usage.mjs) whose contents are not included, so runtime behavior depends on those files.
How this analysis is made

Examples

Design a resource model
SQLiteのデータベースをMCPサーバーで公開したい。テーブルとレコードをリソースとして扱うモデルを設計して、URIスキームとMIMEタイプまで決めてください。
Implement a provider
Design an MCP resource provider for our docs site: define the URI scheme, generate the resource definition JSON, and scaffold the TypeScript provider class.
Validate and harden
Validate this URI scheme with scripts/validate-uri.mjs, check for path traversal risks, and propose a cache invalidation strategy for these resources.

name: resource-oriented-api description: | MCPのリソース指向API設計パターンを提供。URIスキーム設計、リソースモデル定義、 プロバイダー実装、キャッシュ戦略、リソース変換パターンを網羅する。

Anchors: • RESTful Web APIs (Leonard Richardson) / 適用: リソース設計・URI設計 / 目的: REST原則の適用 • MCP Resource Protocol / 適用: リソースプロバイダー実装 / 目的: MCP仕様準拠

Trigger: Use when designing MCP resources, implementing resource providers, or defining URI schemes. MCP resource, resource provider, URI scheme, リソース定義, リソースモデル, API設計 allowed-tools:

  • Read
  • Write
  • Edit
  • Bash
  • Glob
  • Grep

Resource Oriented API

概要

MCPのリソース指向API設計パターンを提供するスキル。URIスキーム設計からリソースプロバイダー実装まで、リソース指向APIの設計・実装を支援する。

ワークフロー

Phase 1: リソースモデル設計

目的: ドメインに適したリソースモデルを設計する

アクション:

  1. リソースとして公開すべきエンティティを特定
  2. リソース間の階層・関連を定義
  3. URIスキームを設計（references/uri-scheme-guide.md参照）
  4. MIME-typeとコンテンツ形式を決定

Task: agents/design-resource-model.md を参照

Phase 2: リソースプロバイダー実装

目的: 設計したリソースモデルをMCPプロバイダーとして実装

アクション:

  1. リソース定義JSONを作成（assets/resource-definition-template.json参照）
  2. プロバイダークラスを実装（assets/resource-provider-template.ts参照）
  3. scripts/validate-resource-definition.mjsで定義を検証
  4. scripts/validate-uri.mjsでURI設計を検証

Task: agents/implement-provider.md を参照

Phase 3: 最適化と検証

目的: パフォーマンスとセキュリティを最適化

アクション:

  1. キャッシュ戦略を適用（references/caching-strategies.md参照）
  2. リソース変換パターンを適用（references/resource-transformation.md参照）
  3. セキュリティチェック（パストラバーサル、スキーム制限）
  4. 最終検証と記録（scripts/log_usage.mjs）

Task仕様（ナビゲーション）

| Task | 起動タイミング | 入力 | 出力 | | --------------------- | -------------- | -------------------- | -------------------- | | design-resource-model | Phase 1開始時 | ドメイン要件 | リソースモデル設計書 | | implement-provider | Phase 2開始時 | リソースモデル設計書 | プロバイダー実装 |

詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照

ベストプラクティス

すべきこと

  • URIは階層的で直感的な構造にする（例: /users/123/posts/456）
  • リソース名は複数形・ケバブケースを使用（例: my-resources）
  • パス深度は最大4レベルに制限
  • 特殊文字は適切にパーセントエンコード
  • キャッシュ戦略を必ず検討する

避けるべきこと

  • 動詞をURIに含めない（例: /getUser は不可、/users/123 を使用）
  • パストラバーサル脆弱性を放置しない
  • 無制限のスキーム許可（許可リストで制限する）
  • キャッシュ無効化戦略なしでの運用

リソース参照

references/（詳細知識）

| リソース | パス | 用途 | | --------------------- | ---------------------------------------------------------------------------------- | ---------------------------- | | URIスキーム設計ガイド | See references/uri-scheme-guide.md | URI構造・命名規則・正規化 | | キャッシュ戦略ガイド | See references/caching-strategies.md | 多層キャッシュ・無効化戦略 | | リソース変換パターン | See references/resource-transformation.md | パイプライン・フィルタリング |

scripts/（決定論的処理）

| スクリプト | 用途 | 使用例 | | ---------------------------------- | ------------------ | --------------------------------------------------------------- | | validate-resource-definition.mjs | リソース定義検証 | node scripts/validate-resource-definition.mjs definition.json | | validate-uri.mjs | URI形式検証 | node scripts/validate-uri.mjs "db://sqlite/users/123" | | log_usage.mjs | フィードバック記録 | node scripts/log_usage.mjs --result success --phase "Phase 3" |

assets/（テンプレート）

| テンプレート | 用途 | | ----------------------------------- | ---------------------------- | | resource-definition-template.json | リソース定義JSONテンプレート | | resource-provider-template.ts | TypeScriptプロバイダー雛形 |

変更履歴

| Version | Date | Changes | | ------- | ---------- | -------------------------------------------- | | 2.0.0 | 2026-01-02 | 18-skills.md仕様に準拠、agents追加、構造改善 | | 1.0.1 | 2025-12-24 | Spec alignment and required artifacts added |

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/resource-oriented-api-design-for-mcp-mmbizjv9/download' --output '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md.part' && mv '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md.part' '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.

Claude Code
test -f '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && test -s '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/resource-oriented-api' && cp -R '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9' '.claude/skills/resource-oriented-api'

Cursor
test -f '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && test -s '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && mkdir -p '.cursor/skills' && test ! -e '.cursor/skills/resource-oriented-api' && cp -R '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9' '.cursor/skills/resource-oriented-api'

Codex
test -f '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && test -s '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md' && mkdir -p '.agents/skills' && test ! -e '.agents/skills/resource-oriented-api' && cp -R '.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9' '.agents/skills/resource-oriented-api'

OpenSkills

OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.

Official OpenSkills installation
openskills install './.skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9'

openskills read 'resource-oriented-api-design-for-mcp-mmbizjv9'

Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.

For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.

openskills sync

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/resource-oriented-api-design-for-mcp-mmbizjv9/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

React Hook Form Best Practices

Development

Master React Hook Form: avoid anti-patterns, manage subscriptions, and handle reset, dirty state, and controlled inputs correctly.

Claude CodeCursorWindsurf+2intermediateSafe 108,623
Skills Guide Bot

Emotion to Mantine Migration

Development

Migrate Emotion styled-components to Mantine components with style props and CSS modules. Use when converting .styled.tsx files or removing @emotion imports.

Claude CodeCursorWindsurf+1intermediateSafe 48,981
Skills Guide Bot

Scope Creep Detector

Development

Analyzes git diffs against a stated intent to detect scope creep, unrelated files, broad PRs, and oversized changes, then suggests keep, split, or justify actions.

Claude CodeCursorCodexintermediateSafe 135,015
Skills Guide Bot