spring-docs-mcp

Local-first MCP stdio server and CLI for generating and searching Spring documentation JSONL indexes.

The MCP server reads local JSONL indexes configured by the user. The optional index CLI command downloads official Spring HTML documentation on demand to create those local indexes. The package does not bundle Spring documentation, does not execute build tools and does not run tests.

Package

@erivelto_muller/spring-docs-mcp

Agent Skill

Agents that support the SKILL.md format can optionally install the portable spring-docs skill.

The MCP is the executable server and indexer. The skill teaches the agent when to call the MCP tools, how to cite indexed evidence, and how to handle missing or weak local documentation matches.

Quick Start

Create a local config:

npx -y @erivelto_muller/spring-docs-mcp init --allowed-root /path/to/projects

Generate a local index from official Spring HTML documentation:

npx -y @erivelto_muller/spring-docs-mcp index \
  --source spring-boot \
  --version 3.4 \
  --max-pages 60

npx -y @erivelto_muller/spring-docs-mcp index \
  --source spring-framework \
  --version 6.2 \
  --max-pages 60

Start the MCP server:

npx -y @erivelto_muller/spring-docs-mcp serve

Generic process-spawned MCP configuration:

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/spring-docs-mcp"],
      "env": {
        "SPRING_DOCS_MCP_CONFIG": "/path/to/spring-docs.yaml"
      }
    }
  }
}

The server can also be started directly:

SPRING_DOCS_MCP_CONFIG=/path/to/spring-docs.yaml \
npx -y @erivelto_muller/spring-docs-mcp serve

Running the package with no subcommand also starts the MCP server, preserving stdio compatibility.

CLI

spring-docs-mcp help
spring-docs-mcp init [--config path] [--data-dir path] [--allowed-root path] [--force]
spring-docs-mcp index --source spring-boot|spring-framework --version current|<major.minor[.patch]> [--max-pages 40]
spring-docs-mcp serve

index downloads official Spring HTML documentation and writes a local JSONL index. For patch versions, the indexer uses the official documentation stream URL when Spring publishes a stream URL, such as 3.4 for Spring Boot 3.4.x or 6.2 for Spring Framework 6.2.x.

By default local files are written under:

~/.config/spring-docs-mcp/config.yaml
~/.local/share/spring-docs-mcp/

Configuration

logging_level: INFO

security:
  allowed_roots:
    - /path/to/projects
  excluded_path_patterns:
    - .git
    - .idea
    - node_modules
    - build
    - target
    - .gradle
    - .env
    - .env.*

limits:
  max_bytes_per_file: 128000
  max_total_project_read_bytes: 512000
  max_search_results: 10

spring_docs:
  index_path: /path/to/spring-docs.jsonl
  generated_index_paths:
    - /path/to/generated-spring-boot-3.4.jsonl
  metadata_path: /path/to/sources.json

Environment overrides:

• SPRING_DOCS_ALLOWED_ROOTS
• SPRING_DOCS_INDEX_PATH
• SPRING_DOCS_GENERATED_INDEX_PATHS
• SPRING_DOCS_METADATA_PATH
• SPRING_DOCS_LOG_LEVEL

Path lists use the platform path delimiter, such as : on macOS/Linux.

JSONL Index Format

Each line must be one JSON object:

{
  "chunk_id": "spring-framework-jdbc-rowmapper",
  "title": "Spring Framework Reference Documentation",
  "url": "https://docs.spring.io/spring-framework/reference/data-access/jdbc.html",
  "source_group": "spring-framework",
  "section": "JdbcTemplate and RowMapper",
  "version": "current",
  "tags": ["jdbc", "row-mapper"],
  "keywords": ["JdbcTemplate", "RowMapper"],
  "summary": "JdbcTemplate delegates row mapping to RowMapper callbacks.",
  "text": "Short curated excerpt or summary used for local search."
}

Keep generated indexes out of this repository unless you have the right to redistribute the content.

Tools

• spring_docs_health
• spring_docs_search
• spring_docs_fetch
• spring_project_detect
• spring_guidance

spring_project_detect only reads bounded Maven/Gradle metadata below configured allowed_roots. It does not execute commands.

Development

npm install
npm run build -w packages/spring-docs-mcp
npm test -w packages/spring-docs-mcp

License

MIT. See LICENSE.