Almanac

Open-source package discovery for AI coding agents.

Your agent finds existing solutions before reinventing the wheel.

The problem

AI coding agents are good at writing code but bad at knowing what already exists. When asked to "add structured logging," they'll write a custom logger instead of finding that pino or structlog already solve the problem. Almanac gives agents a way to search the entire OSS ecosystem — with health and security metadata — before generating custom code.

Quick start

Claude Code:

claude mcp add almanac -- npx -y almanac-mcp

Cursor (.cursor/mcp.json):

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

Claude Desktop (claude_desktop_config.json):

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

What it does

1. Takes an engineering intent (e.g., "YAML parser for Python")
2. Searches package registries (npm, PyPI via Libraries.io)
3. Falls back to web search when structured results are weak (requires optional Tavily API key)
4. Enriches candidates with deps.dev (license, dependencies), OSV (vulnerabilities), and OpenSSF Scorecard (health scores)
5. Returns a ranked candidate set with transparent scoring — every result shows exactly why it's ranked where it is

Tools

| Tool | Description | |---|---| | find_packages | Search for packages matching an engineering intent. Returns ranked candidates with health metadata. | | get_package_health | Deep health check on a specific package — vulnerabilities, Scorecard breakdown, dependency depth. | | compare_packages | Head-to-head comparison of 2-5 packages with license, downloads, security posture. | | discover_mcp_servers | Search the official MCP Registry for existing MCP servers matching a capability. |

Example output

// find_packages({ intent: "structured logging", ecosystem: "npm" })
{
  "candidates": [
    {
      "name": "pino",
      "ecosystem": "npm",
      "version": "9.6.0",
      "description": "super fast, all natural JSON logger",
      "license": "MIT",
      "weeklyDownloads": 6200000,
      "scorecardScore": 7.2,
      "knownVulnerabilities": 0,
      "dependentCount": 3842,
      "rankFactors": {
        "downloads": 67.9,
        "recency": 10,
        "scorecard": 14.4,
        "vulnerabilityPenalty": 0,
        "stars": 12.0,
        "dependents": 10.8,
        "total": 115.1
      }
    },
    {
      "name": "winston",
      "ecosystem": "npm",
      "version": "3.17.0",
      "description": "A logger for just about everything",
      "license": "MIT",
      "weeklyDownloads": 15000000,
      "scorecardScore": 5.8,
      "knownVulnerabilities": 0,
      "dependentCount": 10185,
      "rankFactors": {
        "downloads": 71.8,
        "recency": 5,
        "scorecard": 11.6,
        "vulnerabilityPenalty": 0,
        "stars": 12.9,
        "dependents": 12.0,
        "total": 113.3
      }
    }
  ],
  "searchMetadata": {
    "query": "structured logging",
    "ecosystem": "npm",
    "depth": "standard",
    "totalConsidered": 20,
    "latencyMs": 1847
  }
}

Configuration

All environment variables are optional. Almanac works with zero configuration for npm package discovery.

| Variable | Purpose | Default | |---|---|---| | LIBRARIES_IO_API_KEY | Enables cross-ecosystem search (free at libraries.io/api) | -- | | TAVILY_API_KEY | Enables web search fallback for better PyPI/cross-ecosystem results | -- | | GITHUB_TOKEN | Enhanced repo metadata (stars, issues) | -- | | ALMANAC_CACHE_TTL | Cache TTL in seconds | 3600 | | ALMANAC_MIN_DOWNLOADS | Minimum weekly downloads to include a candidate | 500 |

How ranking works

Results are ordered by transparent heuristic scoring. Every candidate includes a rankFactors object showing:

• downloads (0-70) -- log-scaled weekly download count, the strongest signal
• recency (-8 to +15) -- bonus for recent releases, mild penalty for stale ones (no hard cutoff -- stable packages with millions of downloads rank well regardless)
• scorecard (0-20) -- OpenSSF Scorecard health score
• vulnerabilityPenalty (-15 per CVE) -- harsh penalty per known unpatched vulnerability
• dependents (0-12) -- log-scaled count of packages that directly depend on this one
• stars (0-15) -- minor factor from GitHub stars

This is heuristic ordering, not neutral retrieval. The scores are visible so the calling agent (or you) can override them.

Data sources

• deps.dev -- package metadata, licenses, dependencies (CC-BY 4.0)
• OSV -- open-source vulnerability database
• OpenSSF Scorecard -- automated security health checks
• npm registry -- JavaScript/TypeScript package search
• Libraries.io -- cross-ecosystem package search
• MCP Registry -- MCP server discovery
• Tavily -- AI-optimized web search (optional)

Development

git clone https://github.com/sorenpaetau/almanac-mcp.git
cd almanac-mcp
npm install
npm run build
npm run inspect    # MCP Inspector UI for testing

License

MIT