# AGENTS.md — Flowtivity AI Agent Guide

> This file helps AI agents understand how to interact with Flowtivity's services and APIs.

## Overview

Flowtivity is an AI and automation consultancy that helps businesses redesign workflows using AI. We provide a free website scanning API, MCP server, and various agent integration endpoints.

## Quick Start

### 1. Scan a website

```bash
curl -X POST https://flowtivity.ai/api/insights/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'
```

Returns a `scanId` for tracking.

### 2. Check scan status

```bash
curl https://flowtivity.ai/api/insights/scan/{scanId}/status
```

Poll every 5-10 seconds until `status` is `complete`.

### 3. Get results

```bash
curl https://flowtivity.ai/api/insights/scan/{scanId}/results
```

Returns readiness score (0-100), AEO score (0-100), workflows, opportunities, and key findings.

## MCP Server

Connect to our MCP server for tool-based access:

- **Endpoint**: https://flowtivity.ai/.well-known/mcp
- **Transport**: Streamable HTTP
- **Discovery**: https://flowtivity.ai/.well-known/mcp.json
- **Tools**: 12 tools for scanning, analysis, directory, and analytics

### Available MCP Tools

| Tool | Description | Auth Required |
|------|-------------|---------------|
| `trigger_scan` | Start a new website scan | No (free tier) |
| `list_scans` | List recent scans with filters | No |
| `get_scan` | Get full scan results by ID | No |
| `get_scan_status` | Check scan progress | No |
| `get_opportunities` | Get automation opportunities | No |
| `get_workflows` | Get identified workflows | No |
| `get_playbook` | Get AI automation playbook | Yes |
| `get_directory_listing` | Get directory listing | No |
| `list_directory` | Browse AI Business Directory | No |
| `get_score_breakdown` | Get score details | No |
| `search_insights` | Search across scans | No |
| `get_analytics_summary` | Aggregate analytics | No |

## Authentication

### Free Tier (No auth needed)
- 3-10 scans per day
- Full access to results, directory, and search
- Use `x-mcp-api-key` header when rate limited

### API Key
```bash
curl -H "x-mcp-api-key: YOUR_KEY" https://flowtivity.ai/api/insights/scan/{id}/results
```

### OAuth 2.0 with PKCE
- Authorization: https://flowtivity.ai/api/auth/authorize
- Token: https://flowtivity.ai/api/auth/token
- Metadata: https://flowtivity.ai/.well-known/oauth-authorization-server
- PKCE: S256 code challenge method required

## API Reference

- **OpenAPI Spec**: https://flowtivity.ai/openapi.json (OpenAPI 3.0.3)
- **Health Check**: https://flowtivity.ai/api/health (free, no auth)
- **Developer Portal**: https://flowtivity.ai/developers/

## Agent Discovery Endpoints

| Path | Format | Purpose |
|------|--------|---------|
| `/.well-known/mcp.json` | JSON | MCP server discovery manifest |
| `/.well-known/mcp` | JSON | MCP server card + JSON-RPC endpoint |
| `/.well-known/agent.json` | JSON | Agent capability discovery |
| `/.well-known/agent-card.json` | JSON | Agent card for platform registration |
| `/.well-known/ai-plugin.json` | JSON | ChatGPT plugin manifest |
| `/.well-known/agent-skills/index.json` | JSON | Agent skills registry |
| `/.well-known/llms.txt` | Text | LLM-readable site description |
| `/openapi.json` | JSON | OpenAPI 3.0.3 specification |
| `/?mode=agent` | JSON | Structured agent view of any page |

## Services

1. **AI Education** — Team training (prompt engineering, agent building)
2. **AI Automation** — Custom AI agents and intelligent workflows
3. **AI Agents** — Custom-built agents for complex decisions

## Pricing

- **Free**: Website scan with readiness + AEO scores
- **Simple AI Tools**: From $250/month
- **Custom Automation**: From $1K setup + $400-1K/month
- **Comprehensive**: $9K-50K+ setup

## Contact

- **Email**: aj@flowtivityconsulting.com
- **Website**: https://flowtivity.ai
- **LinkedIn**: https://linkedin.com/company/flowtivity-consulting
- **Founder**: AJ Awan (https://linkedin.com/in/ajawan)

## Response Format

All API responses are JSON. Errors follow this structure:

```json
{
  "error": "error_type",
  "code": "ERROR_CODE",
  "message": "Human-readable description with resolution hint"
}
```

## Rate Limits

- Free tier: 3-10 scans/day, 100 requests/day
- Paid tier: 1000 scans/day, 10000 requests/day
- Check `X-RateLimit-Remaining` header for current status
- Respect `Retry-After` header on 429 responses