# Magnolia CMS Documentation MCP Server (unofficial)

An MCP (Model Context Protocol) server that provides tools to search and retrieve information from the official Magnolia CMS documentation.

## Overview

This MCP server allows AI assistants and language models to search the Magnolia CMS documentation directly, making it easier to get accurate and up-to-date information about Magnolia CMS features, configuration, and best practices.

## Features

- **Documentation Search**: Search through the official Magnolia CMS documentation
- **Structured Results**: Returns formatted search results with titles, URLs, and snippets
- **MCP Compatible**: Works with any MCP-compatible client or AI assistant

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

## Usage

### As a Standalone MCP Server

This server is designed to run as an MCP server using the stdio transport. You can test it directly:

```bash
node src/main.js
```

### With MCP-Compatible Clients

To use this server with MCP-compatible clients (like Claude Desktop, Continue, or other AI assistants), you need to configure the client to connect to this server.

#### Example Configuration for Claude Desktop

Add the following to your MCP configuration file (usually `~/.config/claude-desktop/mcp.json` or similar):

```json
{
  "mcpServers": {
    "magnolia-docs": {
      "command": "node",
      "args": ["/path/to/your/project/src/main.js"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

#### Example Configuration for Other MCP Clients

The server can be configured as a stdio-based MCP server in any compatible client. Refer to your client's documentation for specific configuration instructions.

## Available Tools

### `search_magnolia_docs`

Searches the official Magnolia CMS documentation for the given query.

**Parameters:**
- `query` (string, required): The search term or phrase

**Returns:**
- An array of search results containing:
  - `title`: The title of the documentation page
  - `url`: The URL to the documentation page
  - `snippet`: A brief excerpt from the page

**Example Usage:**
```json
{
  "name": "search_magnolia_docs",
  "arguments": {
    "query": "content types configuration"
  }
}
```

## Project Structure

```
magnolia-docs-mcp/
├── src/main.js          # Main MCP server implementation
├── package.json      # Project dependencies and metadata
└── README.md         # This file
```

## Dependencies

- `@modelcontextprotocol/sdk`: MCP SDK for building MCP servers
- `cheerio`: HTML parsing for extracting search results
- `node-fetch`: HTTP client for making requests to the documentation site

## Development

### Modifying Search Behavior

The search functionality is implemented in the `search_magnolia_docs` tool handler in `main.js`. You can modify:

- Search URL construction
- HTML parsing selectors (currently uses `.search-result`, `.title`, `.snippet`)
- Number of results returned (currently limited to 5)
- Result formatting

### Adding New Tools

To add new tools:

1. Add the tool definition to the `ListToolsRequestSchema` handler
2. Add the tool implementation to the `CallToolRequestSchema` handler
3. Update this README with the new tool documentation

### Testing

You can test the server by running it directly and sending MCP requests via stdio:

```bash
node src/main.js
```

Then send JSON-RPC requests according to the MCP specification.

## Error Handling

The server includes error handling for:
- Network failures when accessing the documentation site
- HTML parsing errors
- Invalid tool requests

Errors are returned as MCP error responses with descriptive messages.

## License

MIT

## Author

Daniel Naranjo

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test your changes
5. Submit a pull request

## Troubleshooting

### Common Issues

1. **"Module not found" errors**: Make sure you've run `npm install` to install dependencies
2. **Connection issues**: Verify that the Magnolia CMS documentation site is accessible
3. **No search results**: The HTML selectors might need updating if the documentation site structure changes

### Debugging

Enable verbose logging by modifying the error handlers in `main.js` to include more detailed error information.

## Roadmap

- [ ] Add support for different documentation sections
- [ ] Implement caching for better performance
- [ ] Add configuration options for search parameters
- [ ] Support for multiple documentation versions
- [ ] Enhanced result filtering and ranking

## Related Resources

- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [Magnolia CMS Documentation](https://docs.magnolia-cms.com)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)