MCP Tools & API

Complete reference for all tools, resources, and REST endpoints exposed by the JFYI server.

JFYI exposes its capabilities through the Model Context Protocol (MCP). Tools are split into two tiers to manage context injection cost:

• Always-on tools — schemas are injected into the agent's context automatically on every session start. Only the highest-value, most-called tools are always-on.
• Discoverable tools — schemas are available on demand via discover_tools. This keeps the initial context footprint small. Agents call discover_tools(tool_name="X") to get the full schema and invoke it.

Always-on MCP tools

These two tools are registered directly in the MCP tool list and their schemas are always present in the agent's context.

record_interaction always-on

Token cost: 120  |  Purpose: write (raw analytics tier)

Records an AI-agent interaction for friction analysis. Call this after each generation to track whether the output was corrected. The analytics engine computes a friction score from was_corrected, correction_latency_s, and num_edits. If the response is long (≥ 500 characters) and uncorrected, a vibe match is also recorded and the confidence of relevant curated rules is boosted.

Returns: Confirmation text with the agent name and computed friction score.

record_interaction(
  agent_name="claude-sonnet-4-6",
  prompt="Refactor the auth module",
  response="...",
  was_corrected=False,
  session_id="my-session-001"
)

get_developer_profile always-on

Token cost: 40  |  Purpose: read (curated profile tier)

Returns the developer's curated rule constitution — rules that the developer has explicitly authored or promoted from notes. These rules describe the developer's coding preferences, communication style, and technical principles. Always call this at session start to ground the agent's behaviour before the first response.

Pass project_context (the git remote URL or directory basename of the current project) to receive project-scoped rules in addition to global ones. Project rules sort first and override global rules in the same category.

Returns: Formatted list of curated rules grouped by category, or a message indicating no rules yet.

# Global profile only
get_developer_profile()

# Include project-scoped rules for "jfyi"
get_developer_profile(project_context="jfyi")

Discoverable MCP tools

These tools are available via discover_tools. To use a discoverable tool, call discover_tools(tool_name="X") to see its schema, then call it via discover_tools(tool_name="X", arguments={...}) or directly if the MCP client has fetched the schema.

discover_tools always-on

Purpose: meta-tool for exploring and invoking the full tool catalogue

Lists all available tools and their token costs, or returns the full schema and usage example for a specific tool. Can also invoke a tool directly when arguments is provided alongside tool_name. Supports an optional query for semantic filtering (requires ITR to be enabled server-side).

# List all tools
discover_tools()

# Get full schema for a specific tool
discover_tools(tool_name="warm_agent")

# Invoke a discoverable tool directly
discover_tools(tool_name="add_profile_note", arguments={"text": "Prefers early returns", "category": "style"})

add_profile_note discoverable

Token cost: 60  |  Purpose: write (raw notes tier)

Files a raw observation about the developer's coding habits or preferences. Notes land in the long-term notes tier, where the developer reviews them and may promote them into curated rules. Write notes at the same level of generality as rules — developer patterns and principles, not implementation details specific to the current project (those belong in CLAUDE.md / GEMINI.md files).

get_agent_analytics discoverable

Token cost: 30  |  Purpose: read (curated analytics tier)

Retrieves comparative friction analytics for all tracked AI agents. Returns correction rates, latency aggregates, and alignment scores per agent. Useful for comparing how different models perform on this developer's workload.

remember_short_term discoverable

Token cost: 25  |  Purpose: write (session scratchpad)

Stores a scratchpad value scoped to the current session. Expires automatically after the TTL (default 3600 s). Useful for passing context between tool calls within a session without consuming permanent profile storage. Values are isolated per (session_id, user_id, key) tuple.

recall_episodic discoverable

Token cost: 40  |  Purpose: read (curated episodic tier)

Retrieves episodic memory summaries written for a session by the background summarizer. Returns interaction summaries and friction event records, ordered by recency. Useful for reconstructing the context of a previous session without re-reading the full interaction transcript.

store_artifact discoverable

Token cost: 20  |  Purpose: context footprint reduction

Stores a large text artifact (crash log, diff, terminal output) on disk and returns a compact handle. Pass the handle to run_local_script to extract focused summaries without loading the full content into the context window. Implements the Compiled View Memory pattern from Phase 1.

run_local_script discoverable

Token cost: 30  |  Purpose: context footprint reduction

Executes a short Python script against a stored artifact. The artifact's file path is available as the pre-defined variable artifact_path. Returns up to 50 lines of stdout. Use this to extract a focused summary from a large artifact without injecting the full content into context.

discover_tools(tool_name="run_local_script", arguments={
  "artifact_id": "abc123",
  "script": "with open(artifact_path) as f: print(f.read()[:500])"
})

warm_agent discoverable

Token cost: 300  |  Purpose: cold-start acceleration

Generates a Vibe Brief for a new agent session. Synthesises the developer's best past interactions (sessions with zero corrections) into 3–5 concise style examples that give the agent an immediate working model of how the developer thinks and communicates. Call once at the start of a fresh session to bootstrap alignment before the first interaction.

If an Anthropic API key is configured (JFYI_ANTHROPIC_API_KEY), the brief is synthesised by an LLM from episodic session summaries. Without a key, it falls back to session statistics and representative interaction excerpts.

Requires at least one session where every recorded interaction had was_corrected=false.

discover_tools(tool_name="warm_agent", arguments={"agent_name": "claude-opus-4-7"})

MCP Resources

MCP Resources are read-only data streams that agents can poll or subscribe to. JFYI exposes one resource.

jfyi://sessions/{session_id}/telemetry

MIME type: application/json  |  Feature: Vibe Telemetry (v2.12.0)

Returns a live alignment snapshot for the specified session. Computes a rolling alignment score over the last 10 interactions and lists recent corrective hints from friction events. Agents can read this resource mid-session to check whether they are drifting and self-correct before the developer needs to intervene.

Payload shape:

{
  "session_id": "my-session-001",
  "alignment_score": 87.5,        // 0–100, higher is better
  "friction_trend": "stable",     // "improving" | "stable" | "worsening"
  "recent_corrections": 1,
  "window_interactions": 8,
  "corrective_hints": [
    "Output was too verbose — developer prefers concise responses"
  ]
}

An empty or unknown session returns alignment_score: 100.0, window_interactions: 0, and an empty hints array.

REST API

The web dashboard is backed by a FastAPI REST API that mirrors the MCP tool surface. All endpoints are served from the same port as the MCP SSE endpoint (default 8080). Authentication uses JWT bearer tokens.

Token cost reference

Token costs represent the approximate number of tokens each tool call consumes in the agent's context window (schema + response). This is used by the discover_tools budget selector when ITR is enabled.