{"id":34281166,"url":"https://github.com/clouatre-labs/math-mcp-learning-server","last_synced_at":"2026-02-23T04:36:01.508Z","repository":{"id":315815064,"uuid":"1060761440","full_name":"clouatre-labs/math-mcp-learning-server","owner":"clouatre-labs","description":"Educational MCP server with math operations, matrix algebra, data visualization, and persistent workspace using FastMCP 2.0","archived":false,"fork":false,"pushed_at":"2026-02-16T03:36:53.000Z","size":717,"stargazers_count":3,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T11:19:33.050Z","etag":null,"topics":["calculator","educational","fastmcp","mathematics","mcp","mcp-server","python","tutorial"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clouatre-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T14:39:29.000Z","updated_at":"2026-02-16T03:30:20.000Z","dependencies_parsed_at":"2026-02-12T17:05:17.217Z","dependency_job_id":null,"html_url":"https://github.com/clouatre-labs/math-mcp-learning-server","commit_stats":null,"previous_names":["huguesclouatre/math-mcp-server","huguesclouatre/math-mcp-learning-server","clouatre/math-mcp-learning-server","clouatre-labs/math-mcp-learning-server"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/clouatre-labs/math-mcp-learning-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Fmath-mcp-learning-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Fmath-mcp-learning-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Fmath-mcp-learning-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Fmath-mcp-learning-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clouatre-labs","download_url":"https://codeload.github.com/clouatre-labs/math-mcp-learning-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clouatre-labs%2Fmath-mcp-learning-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29738080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T02:24:00.660Z","status":"ssl_error","status_checked_at":"2026-02-23T02:22:56.087Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calculator","educational","fastmcp","mathematics","mcp","mcp-server","python","tutorial"],"created_at":"2025-12-16T23:00:37.557Z","updated_at":"2026-02-23T04:36:01.500Z","avatar_url":"https://github.com/clouatre-labs.png","language":"Python","funding_links":[],"categories":["カテゴリ","MCP Servers Directory","Data Analysis \u0026 Exploration Mcp Servers","📦 Other"],"sub_categories":["🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003e開発ツール","Quick Submission"],"readme":"# Math MCP Learning Server\n\n[![PyPI version](https://badge.fury.io/py/math-mcp-learning-server.svg)](https://pypi.org/project/math-mcp-learning-server/)\n[![Python](https://img.shields.io/pypi/pyversions/math-mcp-learning-server)](https://pypi.org/project/math-mcp-learning-server/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/clouatre-labs/math-mcp-learning-server/actions/workflows/ci.yml/badge.svg)](https://github.com/clouatre-labs/math-mcp-learning-server/actions/workflows/ci.yml)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n\u003c!-- mcp-name: io.github.clouatre-labs/math-mcp-learning-server --\u003e\n\nEducational MCP server demonstrating persistent workspace patterns and mathematical operations. Built with [FastMCP 2.0](https://github.com/jlowin/fastmcp) and the official [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk).\n\n**Available on:**\n- [Official MCP Registry](https://registry.modelcontextprotocol.io/) - `io.github.clouatre-labs/math-mcp-learning-server`\n- [PyPI](https://pypi.org/project/math-mcp-learning-server/) - `math-mcp-learning-server`\n\n## Requirements\n\nRequires an MCP client:\n\n- **Claude Desktop** - Anthropic's desktop app\n- **Claude Code** - Command-line MCP client\n- **Goose** - Open-source AI agent framework\n- **OpenCode** - Open-source MCP client by SST\n- **Kiro** - AWS's AI assistant\n- **Gemini CLI** - Google's command-line tool\n- Any MCP-compatible client\n\n## Quick Start\n\n### Cloud (No Installation)\n\nConnect your MCP client to the hosted server:\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"math-cloud\": {\n      \"transport\": \"http\",\n      \"url\": \"https://math-mcp.fastmcp.app/mcp\"\n    }\n  }\n}\n```\n\n### Local Installation\n\n**Automatic with uvx** (recommended):\n\n```json\n{\n  \"mcpServers\": {\n    \"math\": {\n      \"command\": \"uvx\",\n      \"args\": [\"math-mcp-learning-server\"]\n    }\n  }\n}\n```\n\n**Manual installation:**\n```bash\n# Basic installation\nuv pip install math-mcp-learning-server\n\n# With matrix operations support\nuv pip install math-mcp-learning-server[scientific]\n\n# With visualization support\nuv pip install math-mcp-learning-server[plotting]\n\n# All features\nuv pip install math-mcp-learning-server[scientific,plotting]\n```\n\n## Features\n\n- **Cross-Session Persistence**: Variables survive server restarts and session changes\n- **Safe Expression Evaluation**: Secure mathematical expression parsing with security logging\n- **Statistical Analysis**: Mean, median, mode, standard deviation, variance\n- **Financial Calculations**: Compound interest with formatted output\n- **Unit Conversions**: Length, weight, temperature\n- **Function Plotting**: Base64-encoded PNG plots (matplotlib)\n- **Statistical Histograms**: Distribution visualization with indicators\n- **Type Safety**: Full Pydantic validation for all inputs\n- **Comprehensive Testing**: Complete coverage with security validation\n- **Cross-Platform Storage**: Windows, macOS, Linux support\n\n## MCP Implementation\n\n**Primitives:**\n- **Tools**: 17 tools for mathematical operations, persistence, visualization, and matrix operations\n- **Resources**: 1 resource (`math://workspace`) for viewing persistent workspace\n- **Prompts**: 2 prompts (`math_tutor`, `formula_explainer`) for educational interactions\n\n**Transports:**\n- **stdio** - Standard input/output for local clients\n- **HTTP/SSE** - Server-Sent Events for cloud/web clients\n\nWorkspace persists across all transport modes and sessions.\n\n## Available Tools\n\n### Persistent Workspace Tools\n- `save_calculation`: Save calculations to persistent storage for cross-session access\n- `load_variable`: Access previously saved calculations from any MCP client session\n\n### Mathematical Tools\n- `calculate`: Safely evaluate mathematical expressions (supports basic ops and math functions)\n- `statistics`: Perform statistical calculations (mean, median, mode, std_dev, variance)\n- `compound_interest`: Calculate compound interest for investments\n- `convert_units`: Convert between units (length, weight, temperature)\n\n### Visualization Tools\n- `plot_function`: Generate mathematical function plots (base64-encoded PNG)\n- `create_histogram`: Create statistical histograms with distribution analysis\n- `plot_line_chart`: Create line charts for sequential data visualization\n- `plot_scatter_chart`: Create scatter plots for relationship analysis\n- `plot_box_plot`: Create box plots for statistical distribution comparison\n- `plot_financial_line`: Create financial trend plots with bullish/bearish/volatile patterns\n\n### Matrix Operations (requires `[scientific]` extra)\n- `matrix_multiply`: Multiply two matrices with dimension validation\n- `matrix_transpose`: Transpose a matrix (swap rows and columns)\n- `matrix_determinant`: Calculate determinant of square matrices\n- `matrix_inverse`: Compute matrix inverse with singular matrix detection\n- `matrix_eigenvalues`: Calculate eigenvalues (supports complex numbers)\n\n**Note**: Matrix operations require NumPy. Install with `uv pip install math-mcp-learning-server[scientific]`\n\nSee [Usage Examples](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/EXAMPLES.md) for detailed examples of each tool.\n\n## Available Prompts\n\n### Educational Prompts\n- `math_tutor`: Generate structured tutoring prompts for mathematical concepts (configurable difficulty level)\n- `formula_explainer`: Generate comprehensive formula explanation prompts with step-by-step breakdowns\n\nSee [Usage Examples](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/EXAMPLES.md) for detailed examples of each prompt.\n\n## Available Resources\n\n### `math://workspace`\nView your complete persistent workspace with all saved calculations, metadata, and statistics.\n\n**Returns:**\n- All saved variables with expressions and results\n- Educational metadata (difficulty, topic)\n- Workspace statistics (total calculations, session count)\n- Timestamps for tracking calculation history\n\n## Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/clouatre-labs/math-mcp-learning-server.git\ncd math-mcp-learning-server\nuv sync --extra dev --extra plotting\n\n# Test server locally\nuv run fastmcp dev src/math_mcp/server.py\n```\n\n### Testing\n\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Run with coverage\nuv run pytest tests/ --cov=src --cov-report=html --cov-report=term\n\n# Run specific test category\nuv run pytest tests/test_matrix_operations.py -v\n```\n\n**Test Suite:** 126 tests across 5 categories (HTTP, Math, Matrix, Persistence, Visualization)\n**Coverage:** See detailed [testing documentation](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/testing/)\n\n### Code Quality\n\n```bash\n# Linting\nuv run ruff check\n\n# Formatting\nuv run ruff format --check\n\n# Security checks\nuv run ruff check --select S\n```\n\n### Contributing\n\nSee [CONTRIBUTING.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md) for guidelines on submitting changes.\n\n## Documentation\n\n- **[Cloud Deployment Guide](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/CLOUD_DEPLOYMENT.md)**: Prefect Horizon deployment instructions and configuration\n- **[Usage Examples](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/docs/EXAMPLES.md)**: Practical examples for all tools and resources\n- **[Contributing Guidelines](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md)**: Development workflow, code standards, and testing procedures\n- **[Roadmap](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/ROADMAP.md)**: Planned features and enhancement opportunities\n- **[Code of Conduct](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CODE_OF_CONDUCT.md)**: Community guidelines and expectations\n\n## Security\n\n### Safe Expression Evaluation\n\nThe `calculate` tool uses restricted `eval()` with:\n- Whitelist of allowed characters and functions\n- Restricted global scope (only `math` module and `abs`)\n- No access to dangerous built-ins or imports\n- Security logging for potentially dangerous attempts\n\n### MCP Security Best Practices\n\n- **Input Validation**: All tool inputs validated with Pydantic models\n- **Error Handling**: Structured errors without exposing sensitive information\n- **Least Privilege**: File operations restricted to designated workspace directory\n- **Type Safety**: Complete type hints and validation for all operations\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CONTRIBUTING.md) for development workflow, code standards, and testing procedures.\n\nFor maintainers: See [MAINTAINER_GUIDE.md](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/.github/MAINTAINER_GUIDE.md) for release procedures.\n\n## Code of Conduct\n\nThis project adheres to the [Contributor Covenant Code of Conduct](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to hugues+mcp-coc@linux.com.\n\n## License\n\n[MIT License](https://github.com/clouatre-labs/math-mcp-learning-server/blob/main/LICENSE) - Full license details available in the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouatre-labs%2Fmath-mcp-learning-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclouatre-labs%2Fmath-mcp-learning-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclouatre-labs%2Fmath-mcp-learning-server/lists"}