SpringAI MCP Document Server

A Spring Boot implementation of the Model Context Protocol (MCP) document server, based on the original Python implementation from genai-beyond-basics.

This server demonstrates how to create MCP tools, resources, and prompts using Spring AI to read, edit, and format documents.

Features

MCP Tools

• read_doc_contents: Read the contents of a document and return it as a string
• edit_document: Edit a document by replacing old content with new content

MCP Resources

• docs://documents: List all available documents (JSON format)
• docs://documents/{docId}: Fetch a specific document content (text/plain)

MCP Prompts

• format: Reformat a document using Markdown syntax with proper headers, bullet points, tables, etc.

Requirements

• Java 17 or higher
• Maven 3.6 or higher
• Documents directory (docs/) in the project root

Quick Start

1. Clone and Build

git clone <your-repo-url>
cd mcp-document-server
mvn clean compile

2. Create Documents Directory

mkdir docs
echo "This is a sample document with some content." > docs/sample.txt

3. Run the Server

mvn spring-boot:run

The server will start on http://localhost:8080 by default.

Configuration

The server can be configured through application.properties:

# MCP Server Configuration
spring.ai.mcp.server.name=mcp-document-server
spring.ai.mcp.server.version=0.0.1
spring.ai.mcp.server.protocol=STREAMABLE

# Optional: Change server port
# server.port=8081

# Optional: Enable STDIO transport (requires additional configuration)
# spring.ai.mcp.server.stdio=true
# spring.main.banner-mode=off
# logging.pattern.console=
# spring.main.web-application-type=none

Supported Protocols

• STREAMABLE (default): HTTP-based streaming protocol
• STATELESS: Stateless HTTP protocol

Testing with MCP Inspector

1. Start the MCP Inspector

npx @modelcontextprotocol/inspector

2. Configure Connection

In the MCP Inspector interface:

• Transport type: Streamable HTTP
• URL: http://127.0.0.1:8080/mcp

3. Explore

Browse the available:

• Tools: read_doc_contents, edit_document
• Resources: Document listing and individual document access
• Prompts: format prompt for markdown conversion

Usage Examples

Using Tools

Read Document Contents

{
  "tool": "read_doc_contents",
  "arguments": {
    "docId": "sample.txt"
  }
}

Edit Document

{
  "tool": "edit_document",
  "arguments": {
    "docId": "sample.txt",
    "oldContent": "sample document",
    "newContent": "example document"
  }
}

Using Resources

List All Documents

Access resource: docs://documents

Get Specific Document

Access resource: docs://documents/sample.txt

Using Prompts

Format Document to Markdown

{
  "prompt": "format",
  "arguments": {
    "docId": "sample.txt"
  }
}

Integration with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "document-server": {
      "command": "java",
      "args": ["-jar", "target/mcp-document-server-0.0.1-SNAPSHOT.jar"],
      "env": {
        "SPRING_AI_MCP_SERVER_STDIO": "true"
      }
    }
  }
}

Cline Configuration

Configure in your MCP settings:

{
  "mcpServers": {
    "documentServer": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

Project Structure

mcp-document-server/
├── docs/                          # Documents directory
├── src/main/java/
│   └── org/springframework/ai/mcp/sample/server/
│       └── McpServerApplication.java  # Main application with MCP implementations
├── src/main/resources/
│   └── application.properties     # Configuration
├── pom.xml                       # Maven configuration
└── README.md

Development

Key Dependencies

• Spring Boot 3.5.5: Application framework
• Spring AI 1.1.0-SNAPSHOT: MCP server support
• MCP Server WebMVC Starter: HTTP-based MCP server implementation

Extending the Server

To add new MCP capabilities:

1. Tools: Add methods annotated with @McpTool
2. Resources: Add methods annotated with @McpResource
3. Prompts: Add methods annotated with @McpPrompt

Example new tool:

@McpTool(description = "Count words in a document", name = "count_words")
public int countWords(@McpToolParam String docId) {
    String content = readDocContents(docId);
    return content.split("\\s+").length;
}

Comparison with Original Python Implementation

Feature	Python Original	Spring Boot Implementation
Language	Python	Java
Framework	FastAPI	Spring Boot
MCP Library	mcp	Spring AI MCP
Transport	HTTP	HTTP + STDIO support
Tools	✓	✓
Resources	✓	✓
Prompts	✓	✓

License

This project is licensed under the same terms as the original implementation.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Related Links

• Original Python Implementation
• Model Context Protocol Specification
• Spring AI Documentation
• MCP Inspector