# MediaWiki API MCP Server

A Model Context Protocol (MCP) server that allows LLMs to interact with MediaWiki installations through the MediaWiki API as a bot user.

## Features

### Tools

The server provides various MCP tools with the `wiki_` prefix:

|Tool|Description|
|---|---|
|[**`wiki_page_edit`**](docs/tools/wiki_page_edit.md)|Edit or create MediaWiki pages with comprehensive editing options|
|[**`wiki_page_get`**](docs/tools/wiki_page_get.md)|Retrieve page information and content|
|[**`wiki_page_parse`**](docs/tools/wiki_page_parse.md)|Parse page content with support for wikitext processing, HTML generation, metadata extraction, and advanced parsing features|
|[**`wiki_page_compare`**](docs/tools/wiki_page_compare.md)|Compare two pages, revisions, or text content to show differences between them|
|[**`wiki_page_move`**](docs/tools/wiki_page_move.md)|Move pages with support for talk pages, subpages, and redirects|
|[**`wiki_page_delete`**](docs/tools/wiki_page_delete.md)|Delete pages with support for talk pages, watchlist management, and logging|
|[**`wiki_page_undelete`**](docs/tools/wiki_page_undelete.md)|Undelete (restore) deleted MediaWiki pages with comprehensive restoration options|
|[**`wiki_search`**](docs/tools/wiki_search.md)|Search for pages using MediaWiki's search API with advanced filtering|
|[**`wiki_opensearch`**](docs/tools/wiki_opensearch.md)|Search using OpenSearch protocol for quick suggestions and autocomplete|
|[**`wiki_meta_siteinfo`**](docs/tools/wiki_meta_siteinfo.md)|Get overall site information including general info, namespaces, statistics, extensions, and more|

## Installation

1. Clone the repository and checkout the `main` branch

2. Install dependencies using UV:

```bash
uv install
```

3. Set up environment variables:

```bash
export MEDIAWIKI_API_URL="http://mediawiki.test/api.php"
export MEDIAWIKI_API_BOT_USERNAME="YourUserName@YourBotName"
export MEDIAWIKI_API_BOT_PASSWORD="YourBotPassword"
export MEDIAWIKI_API_BOT_USER_AGENT="MediaWiki-MCP-Bot/1.0 (your.email@mediawiki.test)"  # Optional
```

## Usage

### Running the Server

```bash
uv run mediawiki-api-mcp
```

Or directly:

```bash
python -m mediawiki_api_mcp.server
```

### Configuration with Claude Desktop

#### Configuration File Location

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Template Configuration

Add to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "mediawiki-api": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mediawiki-api-mcp",
        "run",
        "mediawiki-api-mcp"
      ],
      "env": {
        "MEDIAWIKI_API_URL": "http://mediawiki.test/api.php",
        "MEDIAWIKI_API_BOT_USERNAME": "YourUserName@YourBotName",
        "MEDIAWIKI_API_BOT_PASSWORD": "YourBotPassword",
        "MEDIAWIKI_API_BOT_USER_AGENT": "MediaWiki-MCP-Bot/1.0 (your.email@mediawiki.test)"
      }
    }
  }
}
```

#### Configuration Instructions

1. Replace `/absolute/path/to/mediawiki-api-mcp` with the actual absolute path to this project directory
2. Update `MEDIAWIKI_API_URL` with your MediaWiki installation's API endpoint
3. Set `MEDIAWIKI_API_BOT_USERNAME` to your bot username (typically in format `YourUserName@YourBotName`)
4. Set `MEDIAWIKI_API_BOT_PASSWORD` to the generated bot password from your wiki's `Special:BotPasswords` page
5. Customize `MEDIAWIKI_API_BOT_USER_AGENT` with appropriate contact information (optional)

##### Bot Password Setup

Create bot credentials at e.g.: `http://mediawiki.test/index.php/Special:BotPasswords`

Required permissions:

- **Basic rights**: Read pages
- **High-volume editing**: Edit existing pages, Create, edit, and move pages
- Additional permissions as needed for your specific use case

##### Security Notes

- Keep your bot credentials secure and never commit them to version control
- Use the principle of least privilege when setting bot permissions
- Monitor bot activity through your MediaWiki's logging interface
- Consider using IP restrictions for additional security

## Development

### Technology Stack

- **MCP SDK**: mcp >= 1.2.0 (using FastMCP pattern)
- **HTTP Client**: httpx >= 0.27.0 for MediaWiki API calls
- **Data Validation**: pydantic >= 2.0.0 for configuration models
- **Environment**: python-dotenv >= 1.0.0 for configuration
- **Testing**: pytest with pytest-asyncio for async testing
- **Code Quality**: ruff for linting, mypy for type checking

### Architecture

- FastMCP server with `@mcp.tool()` decorators
- Separation of concerns: server → handler → client → MediaWiki API
- AsyncIO throughout for non-blocking operations
- Environment-based configuration for MediaWiki credentials

#### Client Layer (`client.py` and `client_modules/`)
- Handles MediaWiki API authentication and requests
- Manages CSRF tokens and session state
- Provides typed methods for API operations

#### Tools Layer (`tools/`)
- Defines MCP tool schemas using JSON Schema
- Separated by functional area (edit, search)
- Ensures all tools have `wiki_` prefix

#### Handlers Layer (`handlers/`)
- Implements actual tool logic
- Handles argument validation and error handling
- Returns properly formatted MCP responses

#### Server Layer (`server.py` and `server_tools/`)
- Main MCP server orchestration
- Routes tool calls to appropriate handlers
- Manages configuration and client lifecycle

### Project Structure

The project is organized into modular components for maintainability:

```
mediawiki-api-mcp/
├── mediawiki_api_mcp/
│   ├── __init__.py
│   ├── server.py             # FastMCP server with tool definitions
│   ├── client.py             # MediaWiki API client
│   ├── client_modules/       # Client modules for API operations
│   │    ├── __init__.py      # Client module exports
│   │    └── client_*.py        # Individual client modules
│   ├── handlers/             # Business logic handlers
│   │    ├── __init__.py      # Handler exports
│   │    └── wiki_*.py        # Individual tool handlers
│   ├── tools/                # Tool schemas
│   │   ├── __init__.py       # Tool schema exports
│   │   └── wiki_*.py         # Individual tool schemas
│   └── server_tools/         # Tool definitions
│       ├── __init__.py       # Tool definition exports
│       └── wiki_*.py         # Individual tool definitions
├── tests/                    # Test suite
│   └── test_*.py             # Test files matching handlers
├── docs/                     # Documentation
│   └── tools/                # Tool-specific documentation
│       └── wiki_*.md         # Individual tool docs
├── pyproject.toml            # Project configuration
└── uv.lock                   # Dependency lock file
```

### Running Tests

```bash
uv run pytest
```

Run specific test modules, e.g.:

```bash
uv run pytest tests/test_server.py
uv run pytest tests/test_tools.py
uv run pytest tests/test_wiki_page_edit.py
uv run pytest tests/test_wiki_search.py
uv run pytest tests/test_wiki_opensearch.py
```

### Code Quality

```bash
# Linting
uv run ruff check

# Type checking
uv run mypy mediawiki_api_mcp
```

## Error Handling

The server implements comprehensive error handling:

- **Configuration errors**: Missing environment variables
- **Authentication errors**: Invalid credentials or permissions
- **API errors**: Network issues, invalid requests
- **Tool errors**: Missing parameters, invalid arguments

All errors are returned as MCP `TextContent` responses for LLM visibility.

## Security

- Bot credentials are required for editing operations
- All API requests include proper User-Agent headers
- CSRF tokens are automatically managed
- Input validation on all tool parameters

## License

[MIT License](https://github.com/entanglr/mediawiki-api-mcp/blob/main/LICENSE)