How sdrshn-nmbr/mc-operator works
Project Type and Purpose
• This is a backend-focused CLI tool (with optional server and client entry points) for building autonomous web agents. It dynamically generates detailed web-automation prompts from simple user commands using large language models (LLMs) and manages those prompts via templates and a repository.
Main Architectural Components
a. Entry Points
• CLI (src/cli.ts) – interactive interface for users to issue commands.
• client.ts / server.ts – optional client/server layer for programmatic access (e.g., via HTTP or other IPC).
b. Agent Layer (src/agent)
• AgentContext – carries state across tasks.
• AgentRunner – orchestrates the high-level flow.
• TaskExecutor – executes individual tasks (calls Prompt generation, LLM, storage, logging).
c. Prompt Management
• PromptGenerator (src/prompt/PromptGenerator.ts) – instantiates templates.
• PromptTemplate (src/prompt/PromptTemplate.ts) – data model for templates.
• Template directories (/templates/system, /templates/tasks, /templates/generated).
d. Storage Layer (src/storage)
• PromptRepository – persists and retrieves generated prompts.
• Underlying storage: local filesystem (./templates/generated) or could extend to DB.
e. Configuration & Settings
• SettingsManager (src/config/SettingsManager.ts) – reads config/settings.json and config/tasks.json.
f. Logging & Analysis
• LogManager (src/logging/LogManager.ts) – collects runtime logs.
• LogAnalyzer (src/logging/LogAnalyzer.ts) – processes and summarizes logs.
g. Utility Components (src/utils)
• LLMClient – wraps calls to external LLM APIs (Anthropic Claude, via ANTHROPIC_API_KEY).
• download-pdf.js – helper script to fetch or save PDFs (supporting media tasks).
External Services
• Puppeteer (for web automation – implied by README).
• LLM API endpoint (Anthropic Claude or similar).
Relationships and Data Flows
1. User issues command → CLI (or client)
2. CLI forwards to AgentRunner via AgentContext
3. AgentRunner selects TaskExecutor (based on task classification from config/tasks.json)
4. TaskExecutor calls PromptGenerator:
– Merges system prompt (templates/system/*.txt) + task prompt (templates/tasks/*.txt) + variables from user.
5. PromptGenerator returns a formatted prompt → TaskExecutor passes it to LLMClient.
6. LLMClient calls external LLM API and receives detailed instructions.
7. TaskExecutor stores the response in PromptRepository → writes to templates/generated/ or via storage API.
8. TaskExecutor may invoke Puppeteer (download-pdf.js or future agent logic) to enact instructions.
9. LogManager records events; LogAnalyzer can later process them.
10. CLI presents results back to the user.
Architectural Patterns & Design Principles
• Layered modular architecture (clear separation: entry, agent, prompt, storage, utils).
• Repository pattern for prompt persistence.
• Template-driven design (system vs. task templates).
• Configuration-driven behavior (config/*.json).
• Single Responsibility (each class handles one concern).
Essential Details to Capture
• All major classes (AgentContext, TaskExecutor, PromptGenerator, LLMClient, PromptRepository, SettingsManager, LogManager).
• Data stores (templates/system, templates/tasks, templates/generated).
• External calls (LLM API, Puppeteer browser automation).
• Configuration flow (config/settings.json → SettingsManager → passed to modules).