argus-mcp/ARGUS_PAPER.md

Argus MCP paper

Purpose

Argus MCP is a read-only market context service for the trader27 stack.

It does not make trading decisions and it does not dispatch actions. Its job is to observe cross-market conditions and publish a compact, explainable description of the current environment so Hermes MCP can reason better.

In short:

• Argus senses
• Hermes interprets and decides
• Trader executes

What Argus provides

Argus exposes two read-only products:

• get_snapshot()
• get_regime()

Snapshot

The snapshot is the rich payload. It contains:

• snapshot_id
• generated_at
• regime
• confidence
• summary
• components
• signals
• impacts
• source_status

Use the snapshot when Hermes wants the full evidence trail.

Regime

The regime payload is the compact payload. It contains:

• snapshot_id
• generated_at
• regime
• confidence
• summary
• components

Use the regime payload when Hermes wants a small, decision-friendly context object.

Provider policy

Finnhub

Finnhub is the primary live source. Use it for the fast layer and for most ETF, equity, volatility, transport, and crypto proxies.

Twelve Data

Twelve Data is optional slow enrichment only. Use it only where Finnhub is missing something useful. It should be treated as sparse context, not the primary engine.

Current policy:

• long cache time, 3 hours
• avoid frequent refreshes
• prefer it only for selective fallback or enrichment symbols

This means Argus should still remain useful even if Twelve Data is removed.

Metals MCP

Metals MCP is the dedicated hard-asset source. Use it for spot metals context and for the precious-metal leg of real-asset pressure. It should be cached and treated as read-only context, not as a decision engine.

Current signal domains

1. Risk appetite

Purpose: measure speculative participation and growth leadership.

Current proxies:

• QQQ
• SPY
• XLK
• SMH
• BTCUSD
• ETHUSD

2. Stress

Purpose: measure volatility and defensive positioning.

Current proxies:

• VXX
• UVXY
• TLT
• inverse contribution from HYG

3. Liquidity

Purpose: measure whether conditions are supportive or tightening.

Current proxies:

• UUP
• HYG
• confirming support from QQQ and BTCUSD

4. Real asset pressure

Purpose: measure hard-asset, inflation, and commodity pressure.

Current proxies:

• GLD
• XAU
• XAG
• XPT
• XPD
• XLE
• USO

5. Transport pressure

Purpose: measure supply chain, freight, airline, logistics, and shipping stress. Transport weakness contributes to fear and stress because it can imply deteriorating demand, strained supply lines, or both.

Current proxies:

• IYT
• JETS
• ZIM
• SBLK
• DHT
• CHRW

Reported states

Argus currently emits these regime states:

• risk_on
• risk_off
• stress
• compression
• real_asset_inflation
• neutral
• no_data

Meanings

risk_on

Speculative participation and liquidity are supportive. Useful for Hermes as a tailwind for breakout or active directional behavior.

risk_off

Defensive positioning is building. Useful for Hermes as a warning against aggressive participation.

stress

Volatility and transport or macro strain dominate. Useful for Hermes as a caution state with elevated fear and fragility.

compression

Signals are subdued, range-like, and not strongly directional. Useful for Hermes as a favorable background for grid or mean-reverting logic.

real_asset_inflation

Hard assets and commodities are leading relative to financial assets. Useful for Hermes as a sign that nominal risk may be mixed even if headline stress is not extreme.

neutral

Signals are mixed and the top regime is not clearly separated. Useful for Hermes as a low-conviction state.

no_data

Not enough inputs are available. Useful for Hermes as a degraded mode signal.

How Hermes should use Argus

Hermes should use Argus as context, not as a command channel.

Recommended pattern:

1. read regime
2. read confidence
3. read components
4. optionally inspect snapshot for evidence details

Suggested Hermes interpretation rules

• compression + range_bound + macro_stress_low
  • favor grid or range-harvesting logic
• risk_on + tech_leadership + liquidity_supportive
  • allow stronger directional bias, but still respect local trader evidence
• stress + transport_stress
  • reduce aggression, widen caution, avoid trusting short-term noise
• real_asset_inflation + gold_bid + energy_pressure_up
  • treat the market as late-cycle or inflation-sensitive, not cleanly bullish
• neutral or low_confidence
  • avoid overreacting to Argus alone

Design principles

• keep the public surface small
• keep the output explainable
• prefer a few strong proxies over symbol sprawl
• prefer cached, auditable data over rate-limit churn
• let Hermes make decisions, not Argus

Next likely improvements

• continue tuning transport versus stress weights
• evaluate whether Twelve Data should remain enabled at all
• later integrate metals-mcp or another dedicated hard-asset source for gold and related signals
• stabilize the state enum contract before deeper Hermes integration