СДАМ ГИА MCP Server

MCP (Model Context Protocol) server for interacting with the СДАМ ГИА educational platform. This server enables LLMs to search and retrieve exam problems, solutions, and answers across multiple subjects.

Features

🔍 Smart Search

• Text Search: Search problems by keywords
• Fuzzy Text Matching: Find problems by condition text with approximate matching
• Catalog Browsing: Explore problems by topics and categories

📚 Problem Retrieval

• Single Problem: Get complete problem details including condition, solution, and answer
• Batch Fetch: Retrieve multiple problems efficiently in one request
• Analog Problems: Discover similar problems automatically

📊 Structured Data

• Multiple Formats: Output in JSON or Markdown
• Rich Metadata: Access images, topics, and problem relationships
• Type Safety: Full TypeScript support with Zod validation

Supported Subjects

• math - Mathematics (профильная)
• mathb - Mathematics (базовая)
• rus - Russian Language
• phys - Physics
• chem - Chemistry
• bio - Biology
• geo - Geography
• hist - History
• soc - Social Studies
• inf - Informatics
• en - English
• de - German
• fr - French
• sp - Spanish
• lit - Literature

Installation

Prerequisites

• Node.js 18+ or 20+
• npm or yarn

Install

npm install
npm run build

Installation

Via npm (Recommended)

npm install -g sdamgia-mcp-server

Or use without installation via npx:

npx sdamgia-mcp-server

From Source

git clone https://github.com/art22017/sdamgia-mcp-server.git
cd sdamgia-mcp-server
npm install
npm run build

Configuration

The server can be configured with any MCP-compatible client. Below are instructions for popular platforms:

Claude Code

Config file locations:

• User scope: ~/.claude.json (available across all projects)
• Project scope: .mcp.json in project root (shared with team)

{
  "mcpServers": {
    "sdamgia": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sdamgia-mcp-server"]
    }
  }
}

Alternative: Via CLI

claude mcp add sdamgia --scope user npx -y sdamgia-mcp-server

Cursor

Config file locations:

• Project: .cursor/mcp.json (in project directory)
• Global: ~/.cursor/mcp.json (home directory)

{
  "mcpServers": {
    "sdamgia": {
      "command": "npx",
      "args": ["-y", "sdamgia-mcp-server"]
    }
  }
}

Or via UI: Settings → Tools & Integrations → MCP Servers → Add New MCP Server

Kilocode

Config file locations:

• Project: .kilocode/mcp.json
• Global: Via Settings → MCP Servers → Edit Global MCP

{
  "mcpServers": {
    "sdamgia": {
      "command": "npx",
      "args": ["-y", "sdamgia-mcp-server"],
      "disabled": false
    }
  }
}

Note: VS Code and CLI configurations are separate in Kilocode.

Google Antigravity

Config file locations:

• macOS/Linux: ~/.config/antigravity/mcp.json or ~/.gemini/antigravity/mcp_config.json
• Windows: %APPDATA%\antigravity\mcp.json

{
  "mcpServers": {
    "sdamgia": {
      "command": "npx",
      "args": ["-y", "sdamgia-mcp-server"],
      "trust": false
    }
  }
}

Or via UI: Agent panel → Three-dot menu → MCP Servers → Manage MCP Servers

Gemini CLI

Config file location: ~/.gemini/settings.json

{
  "mcpServers": {
    "sdamgia": {
      "command": "npx",
      "args": ["-y", "sdamgia-mcp-server"]
    }
  }
}

MCP Inspector (for testing)

npx @modelcontextprotocol/inspector npx -y sdamgia-mcp-server

Usage

Once configured, restart your AI assistant and the server will be available. Use the tools described below.

Available Tools

1. sdamgia_get_problem

Retrieve a specific problem by ID.

Parameters:

• subject (required): Subject code (e.g., "math", "phys")
• problem_id (required): Problem ID (numeric string)
• response_format (optional): "json" or "markdown" (default: "markdown")

Example:

{
  "subject": "math",
  "problem_id": "1001",
  "response_format": "markdown"
}

2. sdamgia_search_problems

Search for problems using text query.

Parameters:

• subject (required): Subject code
• query (required): Search query text (3-500 characters)
• limit (optional): Max results (1-50, default: 20)
• response_format (optional): Output format

Example:

{
  "subject": "math",
  "query": "вероятность",
  "limit": 10
}

3. sdamgia_search_by_text

Find problems by condition text with fuzzy matching.

Parameters:

• subject (required): Subject code
• condition_text (required): Problem text to search (10-1000 characters)
• threshold (optional): Similarity threshold 0-1 (default: 0.6)
• limit (optional): Max results (1-50, default: 20)
• response_format (optional): Output format

Example:

{
  "subject": "phys",
  "condition_text": "Найдите силу тока в цепи если сопротивление",
  "threshold": 0.7,
  "limit": 5
}

Use Cases:

• User has a photo/text of a problem but doesn't know the ID
• Finding similar problems to a given condition
• Matching slight variations in problem wording

4. sdamgia_batch_get_problems

Retrieve multiple problems at once.

Parameters:

• subject (required): Subject code
• problem_ids (required): Array of problem IDs (1-10 items)
• response_format (optional): Output format

Example:

{
  "subject": "inf",
  "problem_ids": ["1001", "1002", "1003"]
}

5. sdamgia_get_catalog

Get complete catalog structure for a subject.

Parameters:

• subject (required): Subject code
• response_format (optional): Output format

Example:

{
  "subject": "math",
  "response_format": "json"
}

6. sdamgia_get_category_problems

Get all problems from a specific category.

Parameters:

• subject (required): Subject code
• category_id (required): Category ID (from catalog)
• limit (optional): Max results (1-50, default: 20)
• response_format (optional): Output format

Example:

{
  "subject": "math",
  "category_id": "174",
  "limit": 30
}

7. sdamgia_get_test

Get all problems from a test.

Parameters:

• subject (required): Subject code
• test_id (required): Test ID (numeric string)
• response_format (optional): Output format

Example:

{
  "subject": "math",
  "test_id": "1770"
}

Architecture

sdamgia-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── constants.ts          # Configuration constants
│   ├── services/
│   │   ├── sdamgia-client.ts # API client (web scraping)
│   │   ├── text-utils.ts     # Fuzzy text matching utilities
│   │   └── formatters.ts     # Output formatters
│   ├── schemas/
│   │   └── input-schemas.ts  # Zod validation schemas
│   └── tools/
│       ├── problem-tools.ts  # Problem-related tools
│       └── catalog-tools.ts  # Catalog-related tools
└── dist/                     # Compiled JavaScript

Design Decisions

1. Comprehensive API Coverage

All major endpoints are exposed as separate tools, giving LLMs maximum flexibility to compose complex workflows.

2. Fuzzy Text Matching

The sdamgia_search_by_text tool uses:

• Levenshtein distance for character-level similarity
• Keyword overlap for semantic matching
• Combined scoring for robust results

This solves the problem of finding problems when text is slightly different (OCR errors, typos, reformatting).

3. Efficient Batch Operations

Batch tool reduces request overhead when multiple problems are needed, improving performance for LLM agents.

4. Response Format Flexibility

Both JSON and Markdown outputs:

• JSON: For programmatic processing and data extraction
• Markdown: For human-readable presentation

5. Request Economy

• Caching: Client could cache frequently accessed data
• Pagination: Limits prevent over-fetching
• Smart Search: Fuzzy search does broad search first, then filters locally

6. Type Safety

Full TypeScript + Zod validation ensures:

• Runtime input validation
• Clear error messages
• IDE autocomplete support

API Endpoints Used

Based on reverse-engineered СДАМ ГИА API:

• GET /{subject}-ege.sdamgia.ru/problem?id={id} - Get problem
• GET /{subject}-ege.sdamgia.ru/search?search={query} - Search
• GET /{subject}-ege.sdamgia.ru/test - Get catalog
• GET /{subject}-ege.sdamgia.ru/test?id={id} - Get test
• GET /{subject}-ege.sdamgia.ru/prob_catalog?category={id} - Get category

Note: This is an unofficial API based on web scraping. No official API exists.

Limitations

1. No Official API: Uses web scraping, may break if site structure changes
2. Rate Limiting: No built-in rate limiting (could be added)
3. No Caching: Each request hits the server (could add Redis/file cache)
4. Russian Only: Platform is in Russian language
5. Network Required: Requires internet connection to СДАМ ГИА servers

Future Enhancements

• [ ] Add request caching layer
• [ ] Implement rate limiting
• [ ] Add support for PDF generation
• [ ] Add image OCR for problem text extraction
• [ ] Add test generation tool
• [ ] Add progress tracking across problems
• [ ] Add HTTP transport for remote deployment

Contributing

Contributions welcome! Please:

1. Follow existing code style
2. Add tests for new features
3. Update documentation
4. Keep tools focused and composable

License

MIT License - See LICENSE file for details

Credits

Based on research from:

• sdamgia-api - Python implementation
• СДАМ ГИА platform - Educational resources

Disclaimer

This is an unofficial tool for educational purposes. Not affiliated with СДАМ ГИА.