JSON 인덱스 파일을 통해 AI 어시스턴트가 원격 마크다운 문서를 읽고 접근할 수 있도록 합니다.
다른 이름 pawcoding/markdown-mcp-resource
- 스타
- 0
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 7일
- 라이선스
- MIT
markdown-mcp-resource MCP란?
JSON 인덱스 파일을 통해 AI 어시스턴트가 원격 마크다운 문서를 읽고 접근할 수 있도록 합니다.
프로젝트 README에서 생성된 요약
markdown-mcp-resource MCP server 정보
AI 어시스턴트에게 원격 문서에 대한 직접적인 접근 권한을 제공하는 것이 이 서버의 주요 기능입니다. 개발자는 웹 서버에 호스팅된 마크다운 파일 모음을 구조화된 MCP 리소스 세트로 변환할 수 있습니다. 서버를 원격 JSON 인덱스 파일로 지정하면, AI 클라이언트가 특화된 URI 패턴을 사용하여 특정 문서 파일을 검색, 목록화 및 읽을 수 있습니다.
사용자는 npx를 통해 로컬에 서버를 설정하며, 명령줄 인수로 index.json 파일의 기본 URL을 제공합니다. 이 설정은 Claude Desktop 또는 OpenCode와 같은 클라이언트에서 작동합니다. 서버는 문서 사이트와의 연결을 관리하며, 마크다운 콘텐츠를 가져오고 메모리 내 캐싱을 사용하여 세션 동안 빠른 액세스를 보장합니다. 중첩된 하위 디렉터리와 루트 상대 경로를 포함한 복잡한 문서 구조를 지원하므로 대규모 기술 매뉴얼에 적합합니다.
활용 사례
- 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를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Claude Desktop에서 서버를 어떻게 설정하나요?
npx를 사용하여 Claude Desktop 설정에 서버를 추가하고, index.json 파일의 전체 URL을 제공하면 됩니다.
인덱스 파일에 필요한 구조는 무엇인가요?
index.json 파일은 'files' 배열을 포함해야 하며, 각 객체는 'name'(.md 제외)과 'route'(전체 URL 또는 루트 상대 경로)를 가져야 합니다.
서버가 하위 디렉터리를 지원하나요?
네, 서버는 중첩된 폴더 및 하위 디렉터리에 문서를 구성하는 방식을 지원합니다.
서버의 성능은 어떻게 관리되나요?
서버는 가져온 마크다운 콘텐츠를 메모리에 캐싱하여 성능을 향상시킵니다.