@agentoffernetwork/skill

MCP Skill for Claude and other AI hosts — search offers via the Agent Offer Network.

An MCP Server that connects Claude Desktop (or any MCP-compatible host) to the Agent Offer Network via @agentoffernetwork/sdk. Users describe what they want in natural language; the host LLM extracts structured intent and the Skill returns ranked, disclosure-labelled recommendations.

Features

• Claude MCP integration -- works as a native Claude Desktop tool
• LLM-driven intent extraction -- the host LLM extracts English keywords, category, and preferences from any language input
• Category decision schemas -- structured domain knowledge helps the LLM ask the right clarifying questions before searching
• Disclosure labels -- every recommendation includes a Sponsored label via formatRecommendation()
• Stable MCP attribution -- requests use the explicit mcp-skill platform adapter instead of implicit runtime guessing

Installation

# Zero-config install for Claude Desktop / Claude Code
npx @agentoffernetwork/skill --install --global

This registers the MCP server in your Claude config and installs the packaged SKILL.md instructions for Claude Code.

If you prefer to wire it manually, use this MCP entry:

{
  "mcpServers": {
    "agentoffernetwork-skill": {
      "command": "npx",
      "args": ["@agentoffernetwork/skill"]
    }
  }
}

Usage with Claude Desktop

The install command above writes to the Claude Desktop config automatically. The config file lives at:

| OS | Config path | |----|-------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Restart Claude Desktop after saving. Then try:

"Help me find noise-cancelling headphones under $300"

Claude will call aon_get_category_schema to understand the electronics domain, then aon_search_offers with extracted keywords and preferences.

Usage with MCP Inspector (Debug)

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Opens a web UI for interactive tool calling and request/response inspection.

Running Locally (stdio)

cd sdk/skill
npm run dev

The server communicates over stdio (stdin/stdout) per the MCP transport spec.

Running Tests

# From sdk/ root
./node_modules/.bin/vitest run --root /absolute/path/to/sdk/skill

Tests use @modelcontextprotocol/sdk Client + InMemoryTransport to exercise both tools end-to-end without stdio.

MCP Tools

aon_search_offers

Search for product/service offers based on structured user intent.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Original user text (any language). Fallback for backend NLU. | | keywords | string[] | No | English keywords extracted by LLM (primary search field). | | category | string | No | Product category (e.g. "electronics", "software_saas", "education"). | | action | enum | No | Intent stage: "discover", "compare", or "purchase". | | userSummary | string | Yes | One concise English sentence summarizing user preferences from the conversation. This is also written into MCP context interests. | | preferences | object | No | { budget_max?: number, features?: string[] } | | limit | number | No | Max results (default 5, max 50). |

At least one of query, keywords, or category must be provided. userSummary should always be present, even when the user is just starting to explore.

Example call:

{
  "name": "aon_search_offers",
  "arguments": {
    "keywords": ["headphones", "noise-cancelling"],
    "category": "electronics",
    "action": "compare",
    "userSummary": "Commuter looking for lightweight noise-cancelling headphones under $300",
    "preferences": { "budget_max": 300, "features": ["wireless"] },
    "limit": 3
  }
}

aon_get_category_schema

Get decision factors for a product category. Call this before searching when the user's intent is vague -- it tells the LLM what clarifying questions to ask.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | category | string | Yes | Category key (e.g. "electronics"), or "all" to list available categories. |

Available categories: electronics, software_saas, education

Example call:

{
  "name": "aon_get_category_schema",
  "arguments": { "category": "electronics" }
}

Returns decision factors (subcategory, use_case, budget_range, key_features) with their possible values.

Architecture

sdk/skill/
├── src/
│   ├── index.ts              # Entry point — stdio transport for local dev
│   ├── tools.ts              # MCP tool definitions + SDK integration
│   └── category-schemas.ts   # Category decision factor data
├── tests/
│   └── search-offers.test.ts # Integration tests via InMemoryTransport
├── package.json
└── tsconfig.json

The tool layer (tools.ts) is decoupled from transport. index.ts wires stdio for local use; a future remote deployment only needs a new entry point with SSE/HTTP transport.

SDK Integration

The Skill uses three @agentoffernetwork/sdk APIs:

import { initialize, createContextForPlatform } from '@agentoffernetwork/sdk';

const client = await initialize({ apiKey: 'your-api-key' });

const response = await client.queryOffers({
  intent: { content: [{ type: 'input_text', text: 'noise-cancelling headphones' }] },
  context: createContextForPlatform('mcp-skill', {
    language: 'en',
    interests: ['noise-cancelling headphones'],
  }),
  pagination: { limit: 5 },
});

for (const offer of response.offers) {
  const md = client.formatRecommendation(offer, { style: 'markdown' });
  // Returns markdown with Sponsored disclosure label + tracking link
}

Current Limitations

• 3 categories -- electronics, software_saas, education (extensible via category-schemas.ts)
• Schema helper scope is narrower than search scope -- use aon_get_category_schema for the 3 built-in demo categories; for broader live-mode categories, search directly
• MCP-first demo skill -- Coze / Dify adapters are exposed at the SDK layer, not via this demo server