JSONインデックスファイルを通じて、AIアシスタントがリモートのMarkdownドキュメントにアクセスし、読み取ることを可能にします。
別名 pawcoding/markdown-mcp-resource
- スター
- 0
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年11月7日
- ライセンス
- MIT
markdown-mcp-resource MCPとは
JSONインデックスファイルを通じて、AIアシスタントがリモートのMarkdownドキュメントにアクセスし、読み取ることを可能にします。
プロジェクトのREADMEから生成された概要
markdown-mcp-resource MCP server について
AIアシスタントにリモートドキュメントへの直接アクセスを提供することが、このサーバーの主な機能です。これにより、開発者はWebサーバー上にホストされているMarkdownファイルの集合を、構造化されたMCPリソースのセットに変換できます。サーバーにリモートのJSONインデックスファイルを指定することで、AIクライアントは専用のURIパターンを使用して、特定のドキュメントファイルを検索、一覧表示、および読み取ることができます。
ユーザーは、コマンドライン引数としてindex.jsonファイルへのベースURLを提供することで、npx経由でローカルにサーバーをセットアップできます。この設定は、Claude DesktopやOpenCodeなどのクライアントで動作します。サーバーはドキュメントサイトへの接続を管理し、Markdownコンテンツの取得を行い、メモリ内キャッシュを使用してセッション中の高速なアクセスを確保します。ネストされたサブディレクトリやルート相対パスを含む複雑なドキュメント構造をサポートしているため、大規模な技術マニュアルにも適しています。
できること
- 1利用可能なドキュメントの検索現在インデックスされており、読み取り可能なすべてのドキュメントファイルを一覧表示するようAIに依頼します。
- 2特定のガイドの読み取り特定のインストールガイドや設定ガイドの全文を取得し、表示するようアシスタントに依頼します。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
markdown-mcp-resource MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude Codeにmarkdown-mcp-resource MCPをインストール
$ claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceCursorにmarkdown-mcp-resource MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}VS Codeにmarkdown-mcp-resource MCPをインストール
.vscode/mcp.json
{
"servers": {
"markdown-mcp-resource": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}VS Code CLIにmarkdown-mcp-resource MCPをインストール
$ code --add-mcp '{"name":"markdown-mcp-resource","type":"stdio","command":"npx","args":["-y","markdown-mcp-resource"]}'Claude Desktopにmarkdown-mcp-resource MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Codexにmarkdown-mcp-resource MCPをインストール
$ codex mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceCodex config.tomlにmarkdown-mcp-resource MCPをインストール
~/.codex/config.toml
[mcp_servers.markdown-mcp-resource] command = "npx" args = ["-y", "markdown-mcp-resource"]
Gemini CLIにmarkdown-mcp-resource MCPをインストール
$ gemini mcp add -s user markdown-mcp-resource npx -- -y markdown-mcp-resourceGemini settings.jsonにmarkdown-mcp-resource MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}自動チェック
実行日 2026年11月15日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能pawcoding/markdown-mcp-resource is public and reachablegithub.com/pawcoding/markdown-mcp-resource ↗合格
- パッケージがこのリポジトリをソースとして指定markdown-mcp-resource names pawcoding/markdown-mcp-resource as sourcenpmjs.com/package/markdown-mcp-resource ↗合格
- ビルドの来歴 (Sigstore 証明)Sigstore attestation for markdown-mcp-resourcenpmjs.com/package/markdown-mcp-resource/v/1.2.3#provenance ↗合格
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-07github.com/pawcoding/markdown-mcp-resource ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from markdown-mcp-resource合格
- パッケージおよびその依存関係に重大な勧告なし未チェック
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るmarkdown-mcp-resource
MCP server that makes remote markdown files available as MCP resources.
Overview
This MCP (Model Context Protocol) server enables AI assistants to access and read markdown documentation from remote URLs. It fetches markdown files listed in a remote JSON index file and makes them available as resources that can be queried and retrieved by MCP-compatible clients.
How It Works
The server:
- Takes a base URL to a JSON index file as a command-line argument (e.g.,
https://my-documentation.com/mcp/index.json) - Expects the index file to contain a list of available markdown files and their routes
- Exposes these files as MCP resources with the URI pattern
markdown://{hostname}/{filename} - Caches fetched content in memory to improve performance
- Provides both resource listing, path completion, and direct content retrieval capabilities
Remote Asset Structure
Your documentation site must be structured as follows:
Required: index.json File
Schema Reference:
The expected format for index.json is formally described in the schema.json file in this repository.
The base URL must point to an index.json file that lists all available markdown files and their routes. Routes can be full HTTP(S) URLs or root-relative paths that start with /, for example:
{
"$schema": "https://raw.githubusercontent.com/pawcoding/markdown-mcp-resource/refs/heads/master/schema.json",
"title": "My Documentation",
"description": "Example documentation index",
"files": [
{
"name": "getting-started",
"route": "https://your-site.com/docs/getting-started.md"
},
{
"name": "api-reference",
"route": "https://your-site.com/docs/api-reference.md"
},
{
"name": "tutorials/basic-setup",
"route": "/docs/tutorials/basic-setup.md"
},
{
"name": "tutorials/advanced-config",
"route": "/docs/tutorials/advanced-config.md"
},
{
"name": "troubleshooting",
"route": "/docs/troubleshooting.md"
}
]
}
Markdown Files
Each file listed in the index must be available at the URL specified in the route field. Root-relative routes resolve against the origin of the index file URL, not the path of the index file:
https://your-site.com/docs/
├── index.json # Lists all available files and their routes
├── getting-started.md # Individual markdown files
├── api-reference.md
├── tutorials/
│ ├── basic-setup.md
│ └── advanced-config.md
└── troubleshooting.md
Important Notes:
- File names in the
namefield of the index should NOT include the.mdextension; theroutefield must be a full HTTP(S) URL or root-relative path to the markdown file and include the.mdextension - Root-relative routes must start with
/; path-relative routes such asdocs/getting-started.mdor./docs/getting-started.mdare not supported - Subdirectories are supported (e.g.,
tutorials/basic-setup)
MCP Client Configuration
OpenCode Configuration
Add this to your OpenCode configuration file (replace with the full URL to your index.json):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-documentation": {
"type": "local",
"command": [
"npx",
"-y",
"markdown-mcp-resource@latest",
"https://my-documentation.com/mcp/index.json"
],
"enabled": true
}
}
}
Claude Desktop Configuration
Add this to your Claude Desktop configuration (replace with the full URL to your index.json):
{
"mcpServers": {
"markdown-docs": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource@latest",
"https://your-documentation-site.com/docs/index.json"
]
}
}
}
Generic MCP Client
For other MCP clients, use the command (replace with the full URL to your index.json):
npx markdown-mcp-resource@latest https://your-documentation-site.com/docs/index.json
Usage Examples
1. Setting Up Documentation
Create an index.json file on your web server:
{
"$schema": "https://raw.githubusercontent.com/pawcoding/markdown-mcp-resource/refs/heads/master/schema.json",
"files": [
{
"name": "introduction",
"route": "https://yoursite.com/docs/introduction.md"
},
{
"name": "installation",
"route": "https://yoursite.com/docs/installation.md"
},
{
"name": "configuration",
"route": "/docs/configuration.md"
},
{
"name": "api/authentication",
"route": "/docs/api/authentication.md"
},
{
"name": "api/endpoints",
"route": "/docs/api/endpoints.md"
},
{ "name": "examples", "route": "/docs/examples.md" },
{
"name": "troubleshooting",
"route": "/docs/troubleshooting.md"
}
]
}
Ensure corresponding markdown files exist:
https://yoursite.com/docs/introduction.mdhttps://yoursite.com/docs/installation.mdhttps://yoursite.com/docs/api/authentication.md- etc.
2. Querying Available Resources
Once configured, your MCP client can:
- List all available markdown resources
- Retrieve specific markdown content
- Search through available documentation files
3. Example Interaction
User: "What documentation is available?"
Assistant: [Lists all files from index.json]
User: "Show me the installation guide"
Assistant: [Retrieves and displays installation.md content]
Features
- Resource Discovery: Automatically lists available documentation from
index.json - Content Caching: Improves performance by caching fetched markdown files
- Path Completion: Supports auto-completion of file paths
- Error Handling: Graceful handling of missing files or network issues
- Subdirectory Support: Organize documentation in nested folders
Troubleshooting
Common Issues
Error: "Invalid base path"
- Ensure the base URL starts with
http://orhttps://and points to yourindex.json - Example:
https://docs.example.com/index.jsonnotdocs.example.com
No resources found
- Verify
index.jsonexists at the base URL - Check that
index.jsoncontains afilesarray with file names and routes - Ensure file names in the
namefield don't include.mdextension
Failed to fetch file
- Verify the markdown files exist at the expected URLs
- Check for CORS issues if accessing from browser environments
- Ensure proper HTTP headers are set on your web server
Performance Issues
- Consider enabling HTTP caching headers on your web server
- The MCP server caches content in memory during the session
Testing Your Setup
-
Verify your
index.jsonis accessible:curl https://your-site.com/docs/index.json -
Test individual markdown files:
curl https://your-site.com/docs/getting-started.md -
Run the MCP server directly:
npx markdown-mcp-resource@latest https://your-site.com/docs/index.json -
Use the MCP Inspector for interactive testing:
Visit https://modelcontextprotocol.io/legacy/tools/inspector to test your MCP server interactively in a web interface.
Development
Local Development
git clone https://github.com/pawcoding/markdown-mcp-resource.git
cd markdown-mcp-resource
npm install
npm run build
npm start https://your-test-site.com/docs/index.json
Visit https://modelcontextprotocol.io/legacy/tools/inspector to test your MCP server interactively in a web interface.
Building
npm run build
Formatting
npm run format
License
MIT - see LICENSE file for details.
markdown-mcp-resource MCPのよくある質問
markdown-mcp-resource MCPをClaude Codeに追加するには
ターミナルでclaude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
markdown-mcp-resource MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
Claude Desktopでのサーバー設定方法を教えてください。
npxを使用して、index.jsonファイルへのフルURLを指定し、Claude Desktopの設定に追加してください。
インデックスファイルに必要な構造は何ですか?
index.jsonファイルには'files'配列を含める必要があります。各オブジェクトには'name'(.mdなし)と'route'(フルURLまたはルート相対パス)を含めてください。
サブディレクトリはサポートされていますか?
はい、サーバーはドキュメントをネストされたフォルダやサブディレクトリで構成することをサポートしています。
パフォーマンスへの対応はどうなっていますか?
サーバーは取得したMarkdownコンテンツをメモリ内にキャッシュすることで、パフォーマンスを向上させています。