Metadata-Version: 2.4
Name: yandex-wiki-mcp
Version: 0.1.0
Summary: MCP server for Yandex Wiki - provides access to corporate wiki pages via Model Context Protocol
Project-URL: Homepage, https://github.com/sashagrande/yandex-wiki-mcp
Project-URL: Repository, https://github.com/sashagrande/yandex-wiki-mcp
Project-URL: Issues, https://github.com/sashagrande/yandex-wiki-mcp/issues
Author-email: Aleksandr Dadeko <dadeko.aleksandr@yandex.ru>
License: MIT
Keywords: ai,claude,mcp,wiki,yandex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: structlog>=24.0.0
Description-Content-Type: text/markdown

# Yandex Wiki MCP Server

MCP (Model Context Protocol) server for accessing Yandex Wiki pages from AI assistants like Claude.

## Features

- **page_get**: Fetch wiki page content and metadata by slug (path)
- **page_get_url**: Get web URL for a wiki page

## Installation

### Using uv (recommended)

```bash
uv run --directory /path/to/yandex-wiki-mcp yandex-wiki-mcp
```

### Development setup

```bash
cd /path/to/yandex-wiki-mcp
uv sync
uv run yandex-wiki-mcp
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WIKI_TOKEN` | Yes* | Yandex OAuth token for Wiki API |
| `TRACKER_TOKEN` | Yes* | Fallback: Yandex OAuth token (same as Tracker) |
| `WIKI_ORG_ID` | Yes* | Yandex organization ID |
| `TRACKER_ORG_ID` | Yes* | Fallback: Yandex organization ID |
| `WIKI_API_BASE_URL` | No | API base URL (default: `https://api.wiki.yandex.net/v1`) |
| `WIKI_WEB_BASE_URL` | No | Web interface URL (default: `https://wiki.yandex.ru`) |
| `REQUEST_TIMEOUT` | No | Request timeout in seconds (default: 30) |

*At least one token (`WIKI_TOKEN` or `TRACKER_TOKEN`) and one org ID (`WIKI_ORG_ID` or `TRACKER_ORG_ID`) must be set.

### Token Fallback

The server supports token fallback for environments where Tracker is already configured:

1. `WIKI_TOKEN` (highest priority)
2. `TRACKER_TOKEN` (fallback)

Same applies for organization ID:

1. `WIKI_ORG_ID` (highest priority)
2. `TRACKER_ORG_ID` (fallback)

### Getting an OAuth Token

1. Go to https://oauth.yandex.ru/
2. Click "Create app"
3. Select "For API access or debugging"
4. Enter app name and contact email
5. Grant necessary permissions for Wiki access
6. Copy the generated token

### Finding Organization ID

1. Open Yandex Tracker
2. Go to Admin settings -> Organizations
3. Copy the ID field value

## MCP Configuration

Add to your Claude MCP configuration (`~/.claude/mcp.json` or project's `.mcp.json`):

```json
{
  "mcpServers": {
    "yandex-wiki": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/yandex-wiki-mcp", "yandex-wiki-mcp"],
      "env": {
        "TRACKER_TOKEN": "${TRACKER_TOKEN}",
        "TRACKER_ORG_ID": "your-org-id"
      }
    }
  }
}
```

## Usage Examples

### Fetch a page

```
Use page_get with slug "teams/dev/onboarding"
```

### Get page URL

```
Use page_get_url with slug "teams/dev/docs"
```

## API Limitations

### No Automatic Redirects

Yandex Wiki API does not follow redirects automatically. If a page has been moved and redirects to another location, the API will return a 404 error.

To handle this:
1. Check the exact page path in the Yandex Wiki web interface
2. Use the final destination path, not the redirect source

### Permission-based Access

API requests carry the same access permissions as the authenticated user. If the user cannot access a page in the web interface, the API will also deny access.

## Development

### Project Structure

```
yandex-wiki-mcp/
├── mcp_wiki/
│   ├── __init__.py
│   ├── __main__.py
│   ├── settings.py
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── server.py
│   │   ├── context.py
│   │   └── errors.py
│   └── wiki/
│       ├── __init__.py
│       ├── client.py
│       └── proto/types/pages.py
├── pyproject.toml
└── README.md
```

### Running locally

```bash
cd /path/to/yandex-wiki-mcp
export TRACKER_TOKEN="your-token"
export TRACKER_ORG_ID="your-org-id"
uv run yandex-wiki-mcp
```

### Code style

The project uses:
- `ruff` for linting and formatting
- `mypy` for type checking
- `structlog` for logging

## License

MIT
