FreshStack MCP

Evidence-backed technology intelligence layer for AI coding agents.
Prevents AI coding assistants from generating outdated, deprecated, or version-incompatible code.

---

The Problem

AI coding assistants frequently generate code using outdated syntax, deprecated methods, or incompatible library versions because their parametric memory lacks real-time awareness of:

1. The project's actual, resolved dependency versions in lockfiles.
2. Official deprecation cycles and migration guides (e.g., Pydantic v1 vs. v2, SQLAlchemy 1.4 vs. 2.0, FastAPI lifespan vs. @app.on_event).
3. Exact version compatibility boundaries.

Core Principle: Evidence Priority

FreshStack does NOT guess or decide what is "modern" from parametric memory.

It verifies technology information strictly against authoritative sources according to an explicit hierarchy:

1. Actual project state and resolved dependency versions (uv.lock, pinned requirements.txt, pyproject.toml)
2. Official version-specific documentation
3. Official migration guides
4. Official changelogs
5. Official package registry metadata (PyPI)
6. Other authoritative sources
7. LLM knowledge only when no stronger evidence exists

The Golden Rule: The project's resolved dependency version has absolute priority over the latest available package version. If a project is pinned to FastAPI 0.115.x, FreshStack never blindly enforces documentation from an incompatible newer release.

---

MVP Scope (Python)

Supported Project Manifests & Lockfiles

• uv.lock
• pyproject.toml (PEP 621 & Poetry)
• requirements.txt

Supported Target Packages

• FastAPI (Lifespan handlers, Pydantic v2 schemas)
• Pydantic (model_dump, model_validate, model_config = ConfigDict, @field_validator, @model_validator)
• SQLAlchemy (2.0 style queries, DeclarativeBase, mapped_column, session.execute(select(...)))
• Alembic (1.12+ connection context migrations)

---

Architecture & Module Structure

freshstack-mcp/
├── freshstack/
│   ├── __init__.py          # Package entry and version
│   ├── config.py            # Environment variables, logging, cache path configuration
│   ├── models.py            # Pydantic v2 schemas (StackInfo, EvidenceSource, AuditViolation)
│   ├── cache.py             # Local SQLite database abstraction with TTL
│   ├── inspect.py           # Stack inspection (uv.lock, pyproject.toml, requirements.txt)
│   ├── pypi.py              # PyPI registry metadata client with local caching
│   ├── knowledge.py         # Authoritative version rules & official documentation citations
│   ├── resolve.py           # Constraint resolution pipeline (VERIFIED, INFERRED, UNKNOWN)
│   ├── audit.py             # Deterministic AST static analysis and violation detection
│   └── server.py            # FastMCP / MCPServer stdio transport server
├── tests/
│   ├── fixtures/            # Sample lockfiles and manifests (uv.lock, pyproject.toml, requirements.txt)
│   ├── test_inspect.py      # Stack inspection unit tests
│   ├── test_cache.py        # SQLite cache and TTL tests
│   ├── test_resolve.py      # Constraint resolution and priority tests
│   ├── test_audit.py        # Deterministic AST audit tests
│   └── test_server.py       # MCP server tool execution tests
├── pyproject.toml           # Modern PEP 621 configuration (uv-compatible)
├── CONTRIBUTING.md          # Development and contribution standards
├── LICENSE                  # MIT License
├── .env.example             # Configuration templates
└── .gitignore               # Clean source control patterns

---

MCP Capabilities & Tools

1. inspect_stack(project_dir: str = ".") -> str

Detects project metadata, Python version, package manager (uv, poetry, pip), and exact resolved versions for all supported libraries.

Example Response:

{
  "project_name": "sample-service",
  "python_version": ">=3.10",
  "package_manager": "uv",
  "detected_files": ["uv.lock", "pyproject.toml"],
  "supported_libraries": {
    "fastapi": "0.115.0",
    "pydantic": "2.9.2",
    "sqlalchemy": "2.0.35",
    "alembic": "1.13.3"
  }
}

2. resolve_constraints(task_description: str, libraries: list = None, project_dir: str = ".") -> str

Given a developer task and target libraries, determines active version constraints, deprecated APIs, recommended replacements, and authoritative evidence citations.

Example Output (excerpt):

{
  "confidence": "VERIFIED",
  "deprecated_patterns": [
    {
      "name": "BaseModel.dict()",
      "status": "deprecated",
      "reason": ".dict() is deprecated in Pydantic v2. Use .model_dump() instead.",
      "replacement": "model.model_dump(mode='python')",
      "evidence": {
        "source_type": "migration_guide",
        "title": "Pydantic V2 Migration Guide - Model Methods",
        "url": "https://docs.pydantic.dev/latest/migration/#changes-to-pydanticbasemodel"
      }
    }
  ]
}

3. freshness_audit(code: str, project_dir: str = ".") -> str

Analyzes generated or developer-written Python code using deterministic static AST analysis. Pinpoints exact line numbers, columns, severity, rationale, and authoritative evidence for deprecated or incompatible APIs.

---

Local-First Privacy Guarantee

FreshStack is designed with privacy as a foundational requirement:

• Local AST Analysis: Code parsing occurs on the local machine via Python's ast module.
• No Secret Transmission: API keys, passwords, environment variables, and unrelated codebase files are never transmitted externally.
• Offline Capable: Operates seamlessly in offline environments using the local SQLite evidence cache.

---

Getting Started

Installation

Clone the repository and install with uv:

git clone https://github.com/freshstack/freshstack-mcp.git
cd freshstack-mcp

# Create virtual environment and install
uv venv .venv
uv pip install -e ".[dev]"

Running the MCP Server

Start the server using stdio transport:

uv run freshstack

Or run via Python directly:

python -m freshstack.server

Integrating with Claude Desktop / Cursor

Add FreshStack to your claude_desktop_config.json:

{
  "mcpServers": {
    "freshstack": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/freshstack-mcp",
        "run",
        "freshstack"
      ]
    }
  }
}

Running Tests

Execute the complete test suite:

uv run pytest -v