Permite que los asistentes de IA accedan y lean documentación remota en markdown a través de un archivo de índice JSON.
También conocido como pawcoding/markdown-mcp-resource
- Stars
- 0
- Herramientas
- —
- Descargas, 30 días
- —
- Última versión
- —
- Último commit
- 7 nov 2026
- Licencia
- MIT
¿Qué es markdown-mcp-resource MCP?
Permite que los asistentes de IA accedan y lean documentación remota en markdown a través de un archivo de índice JSON.
Resumen generado a partir del README del proyecto
Acerca del MCP server de markdown-mcp-resource
La función principal de este servidor es proporcionar a los asistentes de IA acceso directo a documentación remota. Permite a los desarrolladores convertir una colección de archivos markdown alojados en un servidor web en un conjunto estructurado de recursos MCP. Al apuntar el servidor a un archivo de índice JSON remoto, un cliente de IA puede descubrir, listar y leer archivos de documentación específicos utilizando un patrón de URI especializado.
Los usuarios configuran el servidor localmente mediante npx, proporcionando la URL base de un archivo index.json como argumento de línea de comandos. Esta configuración funciona con clientes como Claude Desktop u OpenCode. El servidor gestiona la conexión con tu sitio de documentación, encargándose de la recuperación del contenido markdown y utilizando caché en memoria para garantizar un acceso más rápido durante la sesión. Admite estructuras de documentación complejas, incluyendo subdirectorios anidados y rutas relativas a la raíz, lo que lo hace ideal para manuales técnicos extensos.
Qué puedes hacer con él
- 1Descubrimiento de documentación disponiblePide a la IA que liste todos los archivos de documentación que están indexados y disponibles para su lectura.
- 2Lectura de guías específicasSolicita al asistente que recupere y muestre el texto completo de una guía de instalación o configuración específica.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar markdown-mcp-resource MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar markdown-mcp-resource MCP en Claude Code
$ claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstalar markdown-mcp-resource MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Instalar markdown-mcp-resource MCP en VS Code
.vscode/mcp.json
{
"servers": {
"markdown-mcp-resource": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Instalar markdown-mcp-resource MCP en VS Code CLI
$ code --add-mcp '{"name":"markdown-mcp-resource","type":"stdio","command":"npx","args":["-y","markdown-mcp-resource"]}'Instalar markdown-mcp-resource MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Instalar markdown-mcp-resource MCP en Codex
$ codex mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstalar markdown-mcp-resource MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.markdown-mcp-resource] command = "npx" args = ["-y", "markdown-mcp-resource"]
Instalar markdown-mcp-resource MCP en Gemini CLI
$ gemini mcp add -s user markdown-mcp-resource npx -- -y markdown-mcp-resourceInstalar markdown-mcp-resource MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Verificaciones automáticas
Ejecutado 15 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesiblepawcoding/markdown-mcp-resource is public and reachablegithub.com/pawcoding/markdown-mcp-resource ↗Aprobado
- El paquete indica este repositorio como su origenmarkdown-mcp-resource names pawcoding/markdown-mcp-resource as sourcenpmjs.com/package/markdown-mcp-resource ↗Aprobado
- Procedencia de la compilación (atestación de Sigstore)Sigstore attestation for markdown-mcp-resourcenpmjs.com/package/markdown-mcp-resource/v/1.2.3#provenance ↗Aprobado
- Licencia de código abierto (OSI)MITspdx.org/licenses/MIT.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-11-07github.com/pawcoding/markdown-mcp-resource ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo popular package one edit away from markdown-mcp-resourceAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo verificado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en 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.
Preguntas sobre markdown-mcp-resource MCP
¿Cómo agrego markdown-mcp-resource MCP a Claude Code?
Ejecuta claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resource en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego markdown-mcp-resource MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Cómo configuro el servidor para Claude Desktop?
Añade el servidor a tu configuración de Claude Desktop usando npx y proporcionando la URL completa a tu archivo index.json.
¿Cuál es la estructura requerida para el archivo de índice?
El archivo index.json debe contener un array 'files' donde cada objeto tenga un 'name' (sin el .md) y un 'route' (una URL completa o una ruta relativa a la raíz).
¿El servidor admite subdirectorios?
Sí, el servidor permite organizar la documentación en carpetas y subdirectorios anidados.
¿Cómo gestiona el servidor el rendimiento?
El servidor mejora el rendimiento almacenando en caché el contenido markdown obtenido en la memoria.