Permet aux assistants IA d'accéder et de lire de la documentation markdown distante via un fichier d'index JSON.
Aussi connu sous pawcoding/markdown-mcp-resource
- Étoiles
- 0
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 7 nov. 2026
- Licence
- MIT
Qu'est-ce que markdown-mcp-resource MCP ?
Permet aux assistants IA d'accéder et de lire de la documentation markdown distante via un fichier d'index JSON.
Résumé généré à partir du README du projet
À propos du MCP server markdown-mcp-resource
La fonction principale de ce serveur est de fournir aux assistants IA un accès direct à de la documentation distante. Il permet aux développeurs de transformer une collection de fichiers markdown hébergés sur un serveur web en un ensemble structuré de ressources MCP. En pointant le serveur vers un fichier d'index JSON distant, un client IA peut découvrir, lister et lire des fichiers de documentation spécifiques en utilisant un modèle d'URI spécialisé.
Les utilisateurs configurent le serveur localement via npx en fournissant l'URL de base d'un fichier index.json comme argument de ligne de commande. Cette configuration fonctionne avec des clients tels que Claude Desktop ou OpenCode. Le serveur gère la connexion à votre site de documentation, s'occupe de la récupération du contenu markdown et utilise une mise en cache en mémoire pour garantir un accès plus rapide durant une session. Il prend en charge des structures de documentation complexes, y compris les sous-répertoires imbriqués et les chemins relatifs à la racine, ce qui le rend adapté aux manuels techniques volumineux.
Ce que vous pouvez faire avec
- 1Découverte de la documentation disponibleDemandez à l'IA de lister tous les fichiers de documentation actuellement indexés et disponibles pour la lecture.
- 2Lecture de guides spécifiquesDemandez à l'assistant de récupérer et d'afficher le texte intégral d'un guide d'installation ou de configuration spécifique.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer markdown-mcp-resource MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller markdown-mcp-resource MCP dans Claude Code
$ claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstaller markdown-mcp-resource MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Installer markdown-mcp-resource MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"markdown-mcp-resource": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Installer markdown-mcp-resource MCP dans VS Code CLI
$ code --add-mcp '{"name":"markdown-mcp-resource","type":"stdio","command":"npx","args":["-y","markdown-mcp-resource"]}'Installer markdown-mcp-resource MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Installer markdown-mcp-resource MCP dans Codex
$ codex mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstaller markdown-mcp-resource MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.markdown-mcp-resource] command = "npx" args = ["-y", "markdown-mcp-resource"]
Installer markdown-mcp-resource MCP dans Gemini CLI
$ gemini mcp add -s user markdown-mcp-resource npx -- -y markdown-mcp-resourceInstaller markdown-mcp-resource MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Vérifications automatisées
Exécuté le 15 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessiblepawcoding/markdown-mcp-resource is public and reachablegithub.com/pawcoding/markdown-mcp-resource ↗Réussi
- Le nom du package correspond au dépôt sourcemarkdown-mcp-resource names pawcoding/markdown-mcp-resource as sourcenpmjs.com/package/markdown-mcp-resource ↗Réussi
- Provenance du build (attestation Sigstore)Sigstore attestation for markdown-mcp-resourcenpmjs.com/package/markdown-mcp-resource/v/1.2.3#provenance ↗Réussi
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-07github.com/pawcoding/markdown-mcp-resource ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from markdown-mcp-resourceRéussi
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubmarkdown-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.
Questions sur markdown-mcp-resource MCP
Comment ajouter markdown-mcp-resource MCP à Claude Code ?
Exécutez claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resource dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter markdown-mcp-resource MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Comment configurer le serveur pour Claude Desktop ?
Ajoutez le serveur à votre configuration Claude Desktop en utilisant npx et en fournissant l'URL complète de votre fichier index.json.
Quelle est la structure requise pour le fichier d'index ?
Le fichier index.json doit contenir un tableau 'files' où chaque objet possède un 'name' (sans l'extension .md) et un 'route' (une URL complète ou un chemin relatif à la racine).
Le serveur prend-il en charge les sous-répertoires ?
Oui, le serveur permet d'organiser la documentation dans des dossiers et des sous-répertoires imbriqués.
Comment le serveur gère-t-il les performances ?
Le serveur améliore les performances en mettant en cache le contenu markdown récupéré en mémoire.