Skip to main content
Glama
Algorithmic AI MCP

Algorithmic AI MCP

by ksjpswaroop

Algorithmic AI MCP β€” TAOCP Agent Tools

PyPI version Python 3.10+ License: MIT

Computational First-Principles Engine for Autonomous AI Agents

A semantic adapter layer that exposes Donald Knuth's The Art of Computer Programming (TAOCP) algorithms to AI agents like Hermes-Agent, Claude Desktop, and Cursor via Model Context Protocol (MCP).


🎯 What This Is

252 algorithms from Knuth's TAOCP, made agent-accessible through:

  • βœ… Tiered Exposure β€” Only ~30-40 high-value tools exposed (not all 252)

  • βœ… Safety Guards β€” Combinatorial explosion prevention, timeouts, input validation

  • βœ… Structured Outputs β€” Pydantic models for reliable parsing

  • βœ… Agent-Optimized UX β€” "USE WHEN / DO NOT USE" docstrings guide tool selection

  • βœ… MCP Portable β€” Works with Hermes-Agent, Claude Desktop, Cursor, any MCP client


Related MCP server: math-logic-mcp

πŸš€ Quick Start

Installation

pip install taocp-agent-tools

Basic Usage

from taocp_agent_tools import (
    generate_permutations,
    solve_sat,
    modular_exponentiation,
    recommend_algorithm,
)

# Example 1: Generate permutations safely
result = generate_permutations([1, 2, 3, 4, 5])
print(f"Generated {result.count} permutations")
# Output: Generated 120 permutations

# Example 2: Solve SAT problem
clauses = [[1, 2, -3], [-1, 3], [2, 3]]
result = solve_sat(clauses, num_variables=3)
print(f"Satisfiable: {result.found}")

# Example 3: Cryptographic computation
result = modular_exponentiation(2, 1000000, 997)
print(f"2^1000000 mod 997 = {result.result}")

# Example 4: Get algorithm recommendation
rec = recommend_algorithm("I need to find all patterns in this DNA sequence")
print(f"Recommended: {rec.recommended}")
print(f"Reason: {rec.reason}")

πŸ“¦ Available Tools (Tier 1 MVP)

Combinatorics (4 tools)

  • generate_permutations(items, max_count, derangements_only) β€” Lexicographic permutations with safety guards

  • generate_combinations(items, k, max_count) β€” K-combinations generation

  • generate_integer_partitions(n, max_count) β€” Integer partitions

  • fair_shuffle(items, seed) β€” Knuth/Fisher-Yates shuffle

Exact Cover / SAT / CSP (3 tools)

  • solve_exact_cover(rows, columns, max_solutions) β€” Dancing Links (Algorithm X)

  • solve_sat(clauses, num_variables, find_all) β€” DPLL SAT solver

  • solve_csp(variables, domains, constraints) β€” Constraint satisfaction

Number Theory (5 tools)

  • modular_exponentiation(base, exp, mod) β€” Binary exponentiation

  • modular_inverse(a, m) β€” Extended Euclidean algorithm

  • chinese_remainder(remainders, moduli) β€” Chinese Remainder Theorem

  • primality_test(n, rounds) β€” Miller-Rabin primality test

  • discrete_log(base, target, modulus) β€” Baby-step giant-step

String Analysis (3 tools)

  • multi_pattern_search(text, patterns) β€” Aho-Corasick multi-pattern matching

  • suffix_tree_query(text, query_type) β€” Suffix tree queries

  • burrows_wheeler_transform(text) β€” BWT for compression

Graph Specialized (3 tools)

  • bipartite_matching(left, right, edges) β€” Hopcroft-Karp matching

  • max_flow(graph, source, sink) β€” Ford-Fulkerson max flow

  • strongly_connected_components(graph) β€” Tarjan's SCC algorithm

Symbolic Math (3 tools)

  • symbolic_differentiate(expression, variable, order) β€” Symbolic differentiation

  • simplify_expression(expression) β€” Algebraic simplification

  • evaluate_symbolic(expression, bindings) β€” Expression evaluation

Router (1 meta-tool)

  • recommend_algorithm(task_description, constraints) β€” Algorithm selection advisor


πŸ›‘οΈ Safety Features

Combinatorial Explosion Prevention

# This will raise TAOCPSafetyError
generate_permutations(list(range(15)))
# Error: Refusing to generate 15! = 1,307,674,368,000 permutations

# This works (with limit)
result = generate_permutations(list(range(15)), max_count=1000)
print(f"Generated {result.count} of 1.3 trillion possible")

Timeout Enforcement

# SAT solving with 30-second timeout
result = solve_sat(large_clauses, num_variables=100)
# If timeout: TAOCPSafetyError with helpful message

Input Validation

# All inputs validated before computation
modular_exponentiation(2, -5, 997)
# Error: exponent must be a positive integer

πŸ”Œ MCP Server (Coming Soon)

Make TAOCP tools available to any MCP-compatible agent:

# Install MCP server
pip install taocp-agent-mcp

# Run server
taocp-mcp-server

# Add to Claude Desktop config
{
  "mcpServers": {
    "taocp": {
      "command": "taocp-mcp-server"
    }
  }
}

πŸ“Š Performance

Tool Category

p50

p95

p99

Combinatorics (n≀10)

10ms

50ms

100ms

SAT/CSP (small)

50ms

200ms

500ms

Number Theory

5ms

20ms

50ms

String Analysis (1MB)

100ms

500ms

1s

Graph (100 nodes)

50ms

200ms

500ms


πŸ§ͺ Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest taocp_agent_tools/tests/ -v --cov=taocp_agent_tools

# Run integration tests
pytest taocp_agent_tools/tests/test_agent_integration.py -v

# Check coverage
coverage report --fail-under=95

πŸ“š Documentation

  • PRD β€” Complete 39-section Product Requirements Document

  • Status Report β€” Implementation status, metrics, next steps

  • API Reference β€” Full API documentation (auto-generated)


πŸ—οΈ Architecture

taocp_agent_tools/
β”œβ”€β”€ __init__.py              # Public API exports
β”œβ”€β”€ _safety.py               # Shared guards & validators
β”œβ”€β”€ _types.py                # Pydantic models for structured outputs
β”œβ”€β”€ combinatorics.py         # Tier 1: Permutations, combinations, partitions
β”œβ”€β”€ exact_cover.py           # Tier 1: DLX, SAT, CSP
β”œβ”€β”€ number_theory.py         # Tier 1: Modular arithmetic, primality
β”œβ”€β”€ string_analysis.py       # Tier 1: Aho-Corasick, suffix structures, BWT
β”œβ”€β”€ graph_specialized.py     # Tier 1: Matching, flow, SCC
β”œβ”€β”€ symbolic_math.py         # Tier 1: Differentiation, simplification
β”œβ”€β”€ router.py                # Meta-tool: Algorithm selection advisor
└── tests/
    β”œβ”€β”€ test_combinatorics.py
    β”œβ”€β”€ test_exact_cover.py
    β”œβ”€β”€ test_number_theory.py
    β”œβ”€β”€ test_string_analysis.py
    β”œβ”€β”€ test_graph.py
    β”œβ”€β”€ test_symbolic.py
    β”œβ”€β”€ test_router.py
    └── test_agent_integration.py

πŸŽ“ When to Use TAOCP Tools

βœ… Use TAOCP Tools When:

  • You need exhaustive combinatorial generation (permutations, combinations, partitions)

  • Solving constraint satisfaction problems (Sudoku, scheduling, puzzles)

  • Performing cryptographic computations (modular exponentiation, primality testing)

  • Multi-pattern search in large texts (DNA sequences, virus scanning)

  • Specialized graph algorithms (bipartite matching, max flow, SCC)

  • Symbolic mathematics (differentiation, simplification)

❌ Use Python Stdlib When:

  • Basic sorting (sorted(), list.sort())

  • Basic searching (bisect, in operator)

  • Simple randomization (random.shuffle, random.sample)

  • Basic math (math.factorial, math.comb)


🀝 Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Development Setup

git clone https://github.com/ksjpswaroop/algorithmic-ai-mcp.git
cd algorithmic-ai-mcp
pip install -e ".[dev]"
pre-commit install

πŸ“„ License

Distributed under the MIT License. See LICENSE for more information.


πŸ™ Acknowledgments

  • Donald Knuth for The Art of Computer Programming β€” the foundation of this library

  • TAOCP SDK β€” Core algorithm implementations

  • Hermes-Agent β€” Primary integration target and testing ground

  • MCP Foundation β€” Model Context Protocol for agent tool standardization


πŸ“¬ Contact


πŸš€ Roadmap

v1.0 (MVP) β€” Q4 2026

  • βœ… 15 Tier 1 tools implemented

  • βœ… Safety guards on all tools

  • βœ… Integration tests with >90% accuracy

  • ⏳ PyPI publication

  • ⏳ MCP server packaging

v1.1 β€” Q1 2027

  • String analysis tools (Aho-Corasick, suffix trees, BWT)

  • Graph specialized tools (matching, flow, SCC)

  • Symbolic math tools (differentiation, simplification)

  • Documentation site

v2.0 β€” Q2 2027

  • Tier 2 internal utilities

  • Advanced routing (ML-based tool selection)

  • Caching layer for repeated computations

  • Rate limiting for shared deployments

  • Streaming outputs for large generators


Built with ❀️ for the AI agent ecosystem

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers