{
  "markdown": "# AgentSignal\n\n[![npm version](https://img.shields.io/npm/v/agent-signal)](https://www.npmjs.com/package/agent-signal)\n[![GitHub stars](https://img.shields.io/github/stars/dan24ou-cpu/agent-signal)](https://github.com/dan24ou-cpu/agent-signal)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![MCP Tools](https://img.shields.io/badge/MCP_Tools-23-green)](https://github.com/dan24ou-cpu/agent-signal)\n\n**The collective intelligence layer for AI shopping agents.**\n\nEvery agent that connects makes every other agent smarter. 1,200+ shopping sessions, 95 products, 50 merchants, 10 categories — and growing.\n\n> **Why this exists:** When AI agents shop for users, each agent starts from zero. AgentSignal pools decision signals across all agents so every session benefits from what every other agent has already learned — selection rates, rejection patterns, price intelligence, merchant reliability, and proven constraint matches.\n\n## Quick Start (30 seconds)\n\n**Remote — zero install, instant intelligence:**\n```json\n{\n  \"mcpServers\": {\n    \"agent-signal\": {\n      \"url\": \"https://agent-signal-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n**Local via npx:**\n```bash\nnpx agent-signal\n```\n\n**Claude Desktop / Claude Code:**\n```json\n{\n  \"mcpServers\": {\n    \"agent-signal\": {\n      \"command\": \"npx\",\n      \"args\": [\"agent-signal\"]\n    }\n  }\n}\n```\n\n## One Call to Start Shopping Smarter\n\nThe `smart_shopping_session` tool logs your session AND returns all available intelligence in a single call:\n\n```\nsmart_shopping_session({\n  raw_query: \"lightweight running shoes with good cushioning\",\n  category: \"footwear/running\",\n  budget_max: 200,\n  constraints: [\"lightweight\", \"cushioned\"]\n})\n```\n\n**Returns:**\n- Your session ID for subsequent logging\n- Top picks from other agents in that category\n- What constraints and factors mattered most\n- How similar sessions ended (purchased vs abandoned)\n- Network-wide stats\n\n## 23 MCP Tools\n\n### Smart Combo Tools (recommended)\n\n| Tool | What it does |\n|------|-------------|\n| `smart_shopping_session` | Start session + get category intelligence + similar session outcomes — all in one call |\n| `evaluate_and_compare` | Log product evaluation + get product intelligence + deal verdict — all in one call |\n\n### Buyer Intelligence — Shop Smarter\n\n| Tool | What it tells you |\n|------|-------------------|\n| `get_product_intelligence` | Selection rate, rejection reasons, which competitors beat it and why |\n| `get_category_recommendations` | Top picks, decision factors, common requirements, average budgets |\n| `check_merchant_reliability` | Stock accuracy, selection rate, purchase outcomes by merchant |\n| `get_similar_session_outcomes` | What agents with similar constraints ended up choosing |\n| `detect_deal` | Price verdict against historical data — best_price_ever to above_average |\n| `get_warnings` | Stock issues, high rejection rates, abandonment signals |\n| `get_constraint_match` | Products that exactly match your constraints — skip the search |\n\n### Seller Intelligence — Understand Your Market\n\n| Tool | What it tells you |\n|------|-------------------|\n| `get_competitive_landscape` | Category rank, head-to-head win rate, who beats you and why, price positioning |\n| `get_rejection_analysis` | Why agents reject your product, weekly trends, what they chose instead |\n| `get_category_demand` | What agents are searching for, unmet needs, budget distribution, market gaps |\n| `get_merchant_scorecard` | Full merchant report — stock reliability, price competitiveness, selection rates by category |\n\n### Discovery & Monitoring\n\n| Tool | What it tells you |\n|------|-------------------|\n| `get_budget_products` | Best products within a specific budget — ranked by agent selections, with merchant availability |\n| `get_trending_products` | Products trending up or down — compares current vs previous period selection rates |\n| `create_price_alert` | Set a price alert — triggers when agents spot the product at or below your target |\n| `check_price_alerts` | Check which alerts have been triggered by recent agent activity |\n\n### Write Tools — Contribute Back\n\n| Tool | What it captures |\n|------|-----------------|\n| `log_shopping_session` | Shopping intent, constraints, budget, exclusions |\n| `log_product_evaluation` | Product considered, match score, disposition + rejection reason |\n| `log_comparison` | Products compared, dimensions, winner, deciding factor |\n| `log_outcome` | Final result — purchased, recommended, abandoned, or deferred |\n| `import_completed_session` | Bulk import a completed session retroactively |\n| `get_session_summary` | Retrieve full session details |\n\n## Example: Full Agent Workflow\n\n```\n# 1. Start smart — one call gets you session ID + intelligence\nsmart_shopping_session(category: \"electronics/headphones\", constraints: [\"noise-cancelling\", \"wireless\"], budget_max: 400)\n\n# 2. Evaluate products — get intel as you log\nevaluate_and_compare(session_id: \"...\", product_id: \"sony-wh1000xm5\", price_at_time: 349, disposition: \"selected\")\nevaluate_and_compare(session_id: \"...\", product_id: \"bose-qc45\", price_at_time: 279, disposition: \"rejected\", rejection_reason: \"inferior ANC\")\n\n# 3. Compare and close\nlog_comparison(products_compared: [\"sony-wh1000xm5\", \"bose-qc45\"], winner: \"sony-wh1000xm5\", deciding_factor: \"noise cancellation quality\")\nlog_outcome(session_id: \"...\", outcome_type: \"purchased\", product_chosen_id: \"sony-wh1000xm5\")\n```\n\nEvery step feeds the network. The next agent shopping for headphones benefits from your data.\n\n## Example: Seller Intelligence Workflow\n\n```\n# 1. How is my product performing vs competitors?\nget_competitive_landscape(product_id: \"sony-wh1000xm5\")\n# → Category rank #1, 68% head-to-head win rate, beats bose-qc45 on ANC quality\n\n# 2. Why are agents rejecting my product?\nget_rejection_analysis(product_id: \"bose-qc45\")\n# → 45% rejected for \"inferior ANC\", agents chose sony-wh1000xm5 instead 3x more\n\n# 3. What do agents want in my category?\nget_category_demand(category: \"electronics/headphones\")\n# → Top demands: noise-cancelling (89%), wireless (82%), unmet need: \"spatial audio\"\n\n# 4. How does my store perform?\nget_merchant_scorecard(merchant_id: \"amazon\")\n# → 34% selection rate, 2% out-of-stock, cheapest option 41% of the time\n```\n\n## Categories with Active Intelligence\n\n| Category | Sessions |\n|----------|----------|\n| footwear/running | 150+ |\n| electronics/headphones | 140+ |\n| gaming/accessories | 130+ |\n| electronics/tablets | 130+ |\n| home/furniture/desks | 120+ |\n| fitness/wearables | 118+ |\n| electronics/phones | 115+ |\n| home/smart-home | 107+ |\n| kitchen/appliances | 105+ |\n| electronics/laptops | 98+ |\n\n## Agent Framework Examples\n\nReady-to-run examples in [`/examples`](./examples):\n\n| Framework | File | Description |\n|-----------|------|-------------|\n| **LangChain** | [`langchain-shopping-agent.py`](./examples/langchain-shopping-agent.py) | ReAct agent with LangGraph + MCP adapter |\n| **CrewAI** | [`crewai-shopping-crew.py`](./examples/crewai-shopping-crew.py) | Two-agent crew (researcher + shopper) |\n| **AutoGen** | [`autogen-shopping-agent.py`](./examples/autogen-shopping-agent.py) | AutoGen agent with MCP tools |\n| **OpenAI Agents** | [`openai-agents-shopping.py`](./examples/openai-agents-shopping.py) | OpenAI Agents SDK with Streamable HTTP |\n| **Claude** | [`claude-system-prompt.md`](./examples/claude-system-prompt.md) | Optimized system prompt for Claude Desktop/Code |\n\nAll examples connect to the hosted MCP endpoint — no setup beyond `pip install` required.\n\n## REST API\n\nMerchant-facing analytics at `https://agent-signal-production.up.railway.app/api`:\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/products/:id/insights` | Product analytics — consideration rate, rejection reasons |\n| `GET /api/categories/:category/trends` | Category trends — top factors, budgets, attributes |\n| `GET /api/competitive/lost-to?product_id=X` | Competitive losses — what X loses to and why |\n| `GET /api/sessions` | Recent sessions (paginated) |\n| `GET /api/sessions/:id` | Full session detail |\n| `POST /api/admin/aggregate` | Trigger insight computation |\n| `GET /api/health` | Health check |\n\n## Self-Hosting\n\n```bash\ngit clone https://github.com/dan24ou-cpu/agent-signal.git\ncd agent-signal\nnpm install\ncp .env.example .env  # set DATABASE_URL to your PostgreSQL\nnpm run migrate\nnpm run seed           # optional: sample data\nnpm run dev            # starts API + MCP server on port 3100\n```\n\n## Architecture\n\n- **MCP Server** — Stdio transport (local) + Streamable HTTP (remote)\n- **REST API** — Express on the same port\n- **Database** — PostgreSQL (Neon-compatible)\n- **23 MCP tools** — 17 read (buyer + seller + discovery) + 6 write\n\n## License\n\nMIT\n",
  "bytes": 8801,
  "sha": "f7517075fd97b74c11407b1608750f6cd20378c8c3dea9f7387058f72562ac1f",
  "repo_slug": "dan24ou-cpu/agent-signal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dan24ou_cpu_agent_signal_a4b99585/readme"
}