Epoch

Epoch -- Time Estimation MCP Server

Epoch is a time estimation MCP server that helps engineering leads, agents, and planners who need calibrated duration estimates produce PERT/reference-class estimates and record actuals.

TL;DR: Epoch — time estimation MCP server. Best for engineering leads, agents, and planners who need calibrated duration estimates.

Epoch helps AI agents understand time.

AI can write code, analyze data, and build apps -- but it can't tell you how long something will take, what it'll cost, or whether a deadline is realistic. Epoch fixes that.

---

Show Me

You: "How long will a 15,000 line project take with a small team?"

Claude (using Epoch): COCOMO II nominal: 100 person-months (traditional team) AI-adjusted: 9 person-months (LLM-assisted workflow) Schedule risk: medium (MAPE 15%, based on 28 historical features) Cost estimate (Claude Sonnet): ~$340 in API tokens

You: "How many working days between now and launch?"

Claude (using Epoch): Start: May 1, 2026 End: July 15, 2026 Business days: 54 Weekend days: 16 Holidays: 1 (Independence Day) Total calendar days: 75

You: "Which AI model should we use for a 50k-token job?"

Claude (using Epoch): gemini-2.0-flash: $0.02 -- fast, budget-friendly gpt-4o-mini: $0.02 -- fast, budget-friendly gemini-2.5-pro: $0.37 -- standard, high quality claude-sonnet-5: $0.57 -- standard, high quality Recommendation: gemini-2.0-flash for cost, claude-sonnet-5 for quality

Why Epoch?

Every AI agent hallucinates timelines. "This should take about 2 hours" becomes 2 days. Epoch gives AI grounded, data-driven estimates instead of guesses. It packages established estimation methods (PERT, COCOMO II, Monte Carlo, reference class forecasting) into 26 tools any AI can call -- so your assistant stops guessing and starts calculating.

Works out of the box. Epoch ships with a bundled reference database: task-type correction factors and scope baselines from the maintainer's recorded estimate-vs-actual history plus curated public research, and tool-usage/latency telemetry samples (117,791 across the bundled canary-test and session benchmarks) that keep the token-time bridge grounded. You get reasonable estimates from day one — no data collection or account setup required. If you choose to record your actuals, Epoch's self-improvement engine learns your patterns and gets even more precise over time.

What is MCP?

MCP (Model Context Protocol) is how AI assistants like Claude connect to external tools. Think of it like a plugin system -- you add Epoch with one command, and suddenly your AI assistant can estimate timelines, calculate business days, compare model costs, and predict whether your project will finish on time.

Quick Start

30-second setup -- works in Claude Code, Cursor, VS Code, and Windsurf:

claude mcp add epoch -- npx -y @kyanitelabs/epoch@0.7.0

That's it. Your AI assistant now has 26 time estimation tools.

Or add it to your project's .mcp.json:

{

"mcpServers": { "epoch": { "command": "npx", "args": ["-y", "@kyanitelabs/epoch@0.7.0"] } } }

Limit Epoch tools in Hermes

Use Hermes tools.include to expose only these example tools:

mcp_servers:

epoch: tools: { include: [pert_estimate, cocomo_estimate] }

Agent Skill

Epoch also ships a public agent skill at skills/epoch/SKILL.md. Use $epoch in compatible agent hosts when you want the agent to choose the right Epoch MCP or CLI workflow for time estimates, business-day math, model-cost comparison, schedule risk, and estimate-vs-actual feedback.

What Can Epoch Do?

---

Technical Reference

Everything below is for developers who want to understand the internals, use the CLI or REST API, or contribute to Epoch.

Architecture

Six-layer design with 26 tools for time estimation, scheduling, cost analysis, and feedback:

Tool Reference

Layer 1 -- Core Temporal

`get_current_time` -- Current wall-clock time in any IANA timezone

Input:  { timezone: "America/New_York" }

Output: { iso: "2026-05-01T08:30:00.000-04:00", humanReadable: "Fri, May 1, 2026, 8:30 AM EDT", timezone: "America/New_York", utcOffset: "-04:00" }

`convert_timezone` -- Convert a timestamp between IANA timezones

Input:  { timestamp: "2026-05-01T12:00:00Z", target_tz: "Asia/Tokyo" }

Output: { iso: "2026-05-01T21:00:00.000+09:00", timezone: "Asia/Tokyo", utcOffset: "+09:00", humanReadable: "Fri, May 1, 2026, 9:00 PM JST" }

`parse_duration` -- Parse human-readable duration strings

Input:  { duration_string: "2h30m" }

Output: { input: "2h30m", totalSeconds: 9000, humanReadable: "2 hours 30 minutes" }

`time_math` -- Date arithmetic operations

Input:  { operation: "add_days", operands: { start_date: "2026-05-01", days: 7 } }

Output: "2026-05-08"

Supported operations: add_days, add_business_days, diff, convert_tz, parse_nl, format_duration

Layer 2 -- Calendar Math

`add_business_days` -- Add N business days with holiday awareness (US, UK, FR, DE, JP)

Input:  { start_date: "2026-05-01", days: 5, country: "US" }

Output: { startDate: "2026-05-01", endDate: "2026-05-08", businessDays: 5, countryCode: "US", holidaySupport: "holiday_calendar", humanReadable: "5 business days from 2026-05-01 to 2026-05-08 (US)." }

`count_business_days` -- Count business days between two dates

Input:  { start_date: "2026-05-01", end_date: "2026-05-15", country: "US" }

Output: { startDate: "2026-05-01", endDate: "2026-05-15", businessDays: 10, countryCode: "US", holidaySupport: "holiday_calendar", humanReadable: "10 business days between 2026-05-01 and 2026-05-15 (US)." }

Both tools always include holidaySupport ("holiday_calendar" when the country has a bundled holiday set — US/UK/FR/DE/JP — otherwise "weekends_only") in successful output; country must match ^[A-Za-z]{2}$ — "USA"-style codes are rejected with a readable error.

Layer 3 -- Estimation

`pert_estimate` -- PERT three-point estimation with confidence intervals and urgency scoring

Input:  {

optimistic: 2, most_likely: 4, pessimistic: 12, unit: "hours" } Output: { expected: 5, variance: 2.78, stdDeviation: 1.67, confidence95: [1.67, 8.33], confidence99: [0, 10], unit: "hours", urgencyCategory: "medium", riskLevel: "high", humanReadable: "Expected 2.86–7.14 hours (80% confidence interval); point estimate 5 hours (ledger-recorded basis; adjustedEstimate 5 applies the correction factor). No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.", developerProfile: { mode: "ai_native", correctionFactor: 1 }, adjustedEstimate: 5, rawEstimate: 5, correctionFactor: 1, n: 0, interval: { p50: { lower: 3.87, upper: 6.13 }, p80: { lower: 2.86, upper: 7.14 }, p90: { lower: 2.25, upper: 7.75 }, source: "pert_variance" }, intervalNote: "No task_type was supplied, so this interval is derived from the PERT variance (optimistic/most_likely/pessimistic spread) instead of empirical data.", basisNote: "Interval and point estimate are on the ledger-recorded basis (raw PERT expected × unit factor). adjustedEstimate (5 hours) additionally applies the correction factor (1) and is display-only — it is never recorded or calibrated against." }

(Example from a fresh install with no accumulated feedback; with ≥5 exclusion-filtered matched pairs for the task type, interval.source becomes "empirical_ratio_quantile", n reports the sample size, and intervalPopulation names the ratio population used.)

`cocomo_estimate` -- COCOMO II software sizing with LLM-adapted cost drivers

Input:  {

kloc: 15, reasoning_complexity: 1.2, context_completeness: 1.0, transformation_impact: 0.8, iterative_cycles: 1.5, human_oversight: 1.2 } Output: { kloc: 15, personMonthsNominal: 99.9, personMonthsLlmAdjusted: 8.9, effortMultipliers: { reasoning_complexity: 1.2, context_completeness: 1.0, transformation_impact: 0.8, iterative_cycles: 1.5, human_oversight: 1.2, product: 1.728 }, developerProfile: { mode: "ai_native", correctionFactor: 1.45 } }

LLM-adapted cost drivers include reasoning complexity, context completeness, transformation impact, iterative cycles, and human oversight requirements.

`sprint_forecast` -- Sprint velocity forecasting from historical data

Input:  {

backlog_points: 100, velocity_history: [20, 25, 22, 23], sprint_length_days: 14, hours_per_sprint: 80 } Output: { backlogPoints: 100, averageVelocity: 22.5, requiredSprints: 4.4, pessimisticSprints: 4.9, hoursPerPoint: 3.56, totalHours: 355.6, completionDays: 62, sprintLengthDays: 14, developerProfile: { mode: "ai_native", sprintVelocityPoints: 80, correctionFactor: 1.45 } }

`critical_path` -- Critical Path Method with merge-bias adjustment for parallel tasks

Input:  {

tasks: [ { name: "A", duration: 5, predecessor