freshrss-agent: Instructions file for Codex

AGENTS.md

Agent contract

Tool-neutral rules for any AI agent or human working in this repository. This block is maintained by the fleet standard; edit outside the markers.

• Owner boundary: this repository owns one external system's calls, mappings and MCP tools (spec prefix CONN-FRESHRSS-AGENT-); it depends on the connector SDK only. Feature routing across repositories: ecosystem boundaries.
• Setup: run uv sync --locked, then uvx pre-commit install --hook-type pre-commit --hook-type pre-push.
• Gates: uvx pre-commit run --all-files must pass before you push. Do not bypass hooks to get green.
• Commits: one logical change per commit with a Spec: <ID> trailer (or Spec: none (<reason>)), plus a Co-Authored-By: trailer naming the assisting agent. Stage explicit paths only; never git add -A or git add .. Use your own configured Git identity, never a tool or bot name.
• Org rules: organization AGENTS.md.

Canonical guidance for any AI coding agent or human; tool-specific entry files (for example CLAUDE.md) only import this file. Edit this file.

Tech Stack & Architecture

• Language/Version: Python 3.11+
• Core Libraries: scion-sdk, fastmcp, pydantic-ai
• Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
• Architecture:
  • freshrss_agent/api/: Modular folder for target service client wrappers.
  • freshrss_agent/mcp/: Modular folder for action-routed dynamic MCP tool tags.
  • freshrss_agent/mcp_server.py: Main MCP server entry point and tool registration.

Architecture Diagram

Workflow Diagram

sequenceDiagram
    participant U as User
    participant S as Server
    participant A as Agent
    participant T as MCP Tool
    participant API as External API

    U->>S: Request
    S->>A: Process Query
    A->>T: Invoke Tool
    T->>API: API Request
    API-->>T: API Response
    T-->>A: Tool Result
    A-->>S: Final Response
    S-->>U: Output