Tools reference

#11. MCP tools (spec §19), sygnatury

Serwer operlance, auth tokenem agenta. Każdy wynik: { data, coverage, provenance_summary?, request_id }. Błąd tool (0.6.1): isError: true + { code, message, what_to_do, retry_after_seconds?, details?, request_id } (code = kod z §9; what_to_do = jedno zdanie po angielsku, co agent ma zrobić, bez sekretów). Każdy write: parametry wspólne W = { idempotency_key: string, reason: string }; wynik { status: "executed"|"pending_approval", data?, approval_id? }. Błędy = kody z §9. Scope = { business_id?: string, project_id?: string, personal?: boolean }; Money = { amount_minor: int, currency: string }.

// READ
get_business_summary(business_id, from?, to?)            → FinancialSummary {revenue, costs, by_category[], planned/reserved/actual}
get_business_context(business_id)                        → {business, projects[], summary_30d, free_capital, forecast_status, subscriptions_top[], active_reservations[], pending_approvals[], my_passport,
                                                              recent_decisions: {id, title, decided_on, review: {status, met}, expected[], observed[]}[] /* 0.7.0, ≤5 */,
                                                              agent_costs_30d: {agent_id, name, total_minor, currency}[] /* 0.7.1 */, other_agents_activity: {agent_id, name, action, at, outcome}[] /* 0.7.1: 24 h, max 10, spec §31 */,
                                                              anomalies: {code: "revenue_drop"|"cost_spike"|"no_revenue_14d", message, amount_minor?, data_class}[] /* 0.7.0: revenue 7d vs poprzednie 7d < -30 %; koszt dnia > 3× mediana 30 d w kategorii; brak przychodu 14 dni */ }
get_available_capital(Scope, horizon_days?=30)           → FreeCapital (§6)
get_subscriptions(Scope, status?)                        → Subscription[] (z alokacjami)
get_subscription_capacity(subscription_id? | Scope)      → {subscription_id, unit, total, used, free, utilization, by_workspace[]}[]
get_ad_performance(business_id, from?, to?, platform?)   → {platform, spend: P/R/A, results?, pacing?}[]
get_cashflow_forecast(Scope, horizon: 7|30|90 | {from,to}) → Forecast (§7)
get_project_health(business_id, project_id?)             → {status[], reasons[]} (bez score)
get_daily_brief(date?, business_id?)                     → {date, business_id|null, highlights[], alerts[], upcoming[], approvals_pending, goal_deviations[], agent_costs_30d: {agent_id, name, total_minor, currency}[] /* 0.7.1 */}
get_goals(Scope, include_archived?=false)                → (Goal & {progress})[]   (0.5.2, §2.17; tylko cele w zasięgu grantów)
get_decision_outcomes(Scope, since?, limit?=20)          → DecisionOutcome[]        (0.5.2, §2.18; własne decyzje agenta)
get_onboarding(resource?)                                → Onboarding (0.5.2, spec §21; 0.6.1: `resource` = `business:<id>` | `project:<id>` zawęża sekcje do jednego zasobu) + MCP resource `operlance://onboarding` (markdown ≤ 2 000 tokenów, bez sekretów):
  Onboarding = { about: string, my_passport: { agent: {id, name, kind}, grants: string[] /* "ads:execute@business:<id> ≤ 500 PLN/akcja, 10%/dzień" */, expires_at, token_expires_at },
    businesses_accessible: {id, name, currency}[], forbidden: string[], limits: PassportGrant["limits"][], goals: Goal[],
    concepts: { planned_vs_actual, reservations, decision_journal, approvals }: Record<string,string>, examples: {title, tools: string[]}[] }

// WRITE (W wymagane)
create_expense(W, Scope, Money, occurred_on, category, description)                         → FinancialEvent
create_recurring_expense(W, Scope|allocations[], name, vendor, Money, billing_interval, next_charge_on, plan?, capacity?[]) → Subscription
create_planned_expense(W, Scope, Money, expected_on, category, description)                → FinancialEvent
reserve_budget(W, Scope, Money, purpose, category, period_start, period_end)               → BudgetReservation
allocate_shared_expense(W, subscription_id, allocations: {Scope, method, share_bps}[])     → SubscriptionAllocation[]
propose_ad_budget_change(W, business_id, platform, campaign_id?, current: Money, proposed: Money) → Approval (zawsze; execute w MVP = zapis planu, bez wywołań platform)
request_permission(W, scope, level, resource, limits?, expires_at?)                        → Approval
create_decision(W, Scope, title, rationale, expected_impact?, expected?[], action_ref?, refs?[]) → FinancialEvent(agent_action) (§2.18)
propose_goal(W, Scope, metric, comparator, target_value, currency?, title?, deadline?, agent_id?) → Approval (zawsze 202, action=create_goal; §2.17)

// 0.7.0 (spec §29 What-if, §25 Agent Requests, §28 review)
simulate_scenario(Scope, horizon_days?=7|30|90, changes: Change[1..20]) → Simulation        // READ (finances:observe + forecast:observe); bez zapisu, bez Idempotency-Key
  Change = { kind: "add_expense", amount: Money, on?, category?, label? } | { kind: "add_recurring", amount: Money, billing_interval, interval_count?=1, next_charge_on?, label? }
         | { kind: "cancel_subscription", subscription_id } | { kind: "change_ad_budget", platform, current: Money, proposed: Money /* budżety DZIENNE */, campaign_id?, from? } | { kind: "add_revenue", amount: Money, on?, label? }
  ForecastSnapshot = { closing_cash_minor, min_cash_minor, net_minor, projected_in_minor, projected_out_minor, runway_days|null, free_capital_minor, break_even_on|null, statuses[] }
  Simulation = { scope, currency, horizon_days, from, to, changes[], baseline: ForecastSnapshot, simulated: ForecastSnapshot,
                 delta: { closing_cash_minor, min_cash_minor, net_minor, runway_days|null, free_capital_minor, break_even_on: {from, to} },
                 unmodeled_minor /* część zmiany nieodwzorowana eventami, odjęta analitycznie */, data_class: "estimated", notes: string[] }
request_data(W, kind: "connect_integration"|"provide_data", details: { provider? /* connect */, field? /* provide, np. cash_snapshot */, why, impact_on_coverage? }) → Approval (202, action = kind)
get_decision_review(decision_id)                          → DecisionOutcome (§2.18; własne decyzje)
get_agent_economics(agent_id?, business_id?, from?, to?)  → AgentEconomics (0.7.1, spec §32; agent: tylko własne)

// 1.0.0-rc.2 (Agentowy 66), experimental
get_personal_summary(from?, to?)                          → FinancialSummary dla personal (scope `finances:observe@personal`; brak grantu → scope_denied z what_to_do „poproś o grant @personal")
get_personal_forecast(horizon?: 7|30|90 | {from,to}, include_points?) → Forecast dla personal (jak wyżej)
plan_capacity(needs: {unit, amount, business_id}[1..10], W?) → { per_need: { need, covered_by: {subscription_id, free}|null, shortfall: int, suggestion: "allocate"|"upgrade"|"buy_new", est_cost_minor: int|null, proposed_allocations[] }[], proposals: Approval[] /* tylko z W: Approval allocate_shared_expense, nic nie kupuje */ }
  AgentEconomics = { agent_id, period: {from,to}, currency, cost: { total_minor, runtime_minor /* agent_runtime z ledgera */, tools_minor /* alokacje subskrypcji z SubscriptionAllocation.agent_id */, by_category[] },
                     actions: { total, by_tool: Record<string,int>, denied: int }, approvals: { proposed, approved, rejected, expired, pending },
                     impact: { reviewed_decisions, met, missed, revenue_generated_minor|null, cost_saved_minor|null, data_class },
                     roi: { value: number|null, data_class: "estimated"|"unavailable", note } }

#Transport zdalny MCP (1.0.0-rc.2, Zadanie 81/84)

• Ten sam serwer operlance działa po stdio (paczka @operlance/mcp, token w env OPERLANCE_TOKEN) i po Streamable HTTP: POST <MCP_PUBLIC_URL>/mcp z nagłówkiem Authorization: Bearer agt_… per żądanie (stateless: brak sesji MCP, sessionIdGenerator wyłączony, odpowiedzi JSON), GET /health → {status:"ok", transport:"streamable-http", contract}; żadnych tokenów w env usługi. Staging: usługa mcp (Railway, apps/mcp/Dockerfile.mcp, port 8788) rozmawia z API przez sieć prywatną (OPERLANCE_API_URL=http://api.railway.internal:4000); adres publiczny tymczasowo domena Railway, docelowo mcp.operlance.app (Q20, PRODUCTION §2).
• Auth i uprawnienia identyczne jak REST (token agenta → Passport; allowed_cidrs widzą IP klienta z X-Forwarded-For); rate limit per token 120/min (na stagingu w pamięci procesu, docelowo rate_limits w DB); brak tokenu/zły token → HTTP 401 z {code:"unauthenticated"}; przekroczenie → 429 + Retry-After; błędy tool jak §11 (isError, what_to_do). CORS wyłączony (klienci MCP to procesy, nie przeglądarki); nagłówki z SECURITY §3; limit body 1 MB.
• Klienci: claude mcp add --transport http operlance <MCP_PUBLIC_URL>/mcp --header "Authorization: Bearer …"; Claude Desktop/Cursor: { "url": "…/mcp", "headers": { "Authorization": "Bearer …" } } (token wklejany przez Ownera z panelu, nigdy w repo/docs).

#10. Scopes i poziomy autonomii (spec §22-23)

Scopes (string): finances, subscriptions, ads, forecast, expenses, planned_expenses, budget_reserve, allocations, goals, decisions. Grant = scope × level × resource (all | business:<id> | project:<id> | personal) × limits. Zapis skrótowy: ads:execute@business:<id>.

• Konflikt zasobu między agentami (0.7.1, spec §31): write/propozycja dotycząca tego samego zasobu (kampania, subskrypcja, rezerwacja), dla którego istnieje pending Approval innego agenta → 409 state_conflict z details.conflict {approval_id, agent_id, action} (AuditEntry denied, AuthzDecision.deny.code += state_conflict). Check konfliktu i INSERT Approval wykonywane w jednej transakcji (authorize dostaje tx), żeby dwie równoległe propozycje nie przeszły obie.
• Limity dzienne/miesięczne liczą także kwoty OCZEKUJĄCYCH Approval agenta (status=pending), ochrona przed podwójnym budżetowaniem (spec §31): usage = Σ wykonane akcje w oknie + Σ pending Approval z amount_minor w oknie; po rejected/expired/cancelled kwota wraca do puli; approved przechodzi z „pending” do „wykonane” bez podwójnego liczenia. limit_checked w AuditEntry rozbija usage na executed_minor i pending_minor. Odmowa limit_exceeded (0.6.1): AuditEntry denied z limit_checked[] (jeden wpis per sprawdzony limit: {limit_key, limit_minor|pct, usage_minor, attempted_minor, currency, window}).
• Samoobsługowe dla każdego aktywnego agenta (zamierzone, 0.8.1): GET /me, GET /agents/me, GET /agents/:id (własny), GET /agents/:id/passport (własny), POST /permission-requests, POST /data-requests, GET /approvals (własne): nie wymagają grantu, bo agent musi móc poznać własne uprawnienia i poprosić o więcej; zawsze audytowane.
• Default deny. Brak grantu = 403 scope_denied (z audit denied). personal nigdy nie wynika z all, wymaga jawnego grantu @personal.
• Grant na business obejmuje jego projekty. Grant wygasły (expires_at) = brak grantu.
• ads:execute limit max_change_pct_per_day (np. 10 = ±10%).
• Wymagany scope: czytanie podsumowań finances:observe; create_expense→expenses; create_recurring_expense→subscriptions+expenses; create_planned_expense→planned_expenses; reserve_budget→budget_reserve; allocate_shared_expense→allocations; propose_ad_budget_change→ads (≥recommend); create_decision→decisions; get_decision_outcomes, get_decision_review→decisions (observe); simulate_scenario→finances+forecast (observe); request_data→dowolny aktywny agent (jak request_permission); get_goals, get_onboarding→goals (observe; onboarding = własny passport, zawsze dozwolone); propose_goal→goals (≥ recommend, wynik zawsze Approval).