Skip to content

Commit 8fa9b42

Browse files
anhmtkanhmtk
authored
Update README.md
1 parent 72a49af commit 8fa9b42

1 file changed

Lines changed: 60 additions & 154 deletions

File tree

‎README.md‎

Lines changed: 60 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1,189 +1,95 @@
1-
# AgentShare
1+
<p align="center">
2+
<img src="https://agentshare.dev/static/logo.png" alt="AgentShare" width="120">
3+
</p>
24

3-
![Production Ready](https://img.shields.io/badge/status-production--ready-brightgreen)
4-
[![MCP Server](https://img.shields.io/badge/MCP-Streamable%20HTTP-5C6BC0?style=flat)](https://agentshare.dev/mcp/)
5-
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
6-
[![REST API](https://img.shields.io/badge/API-agentshare.dev-20BE86?style=flat)](https://agentshare.dev/openapi.json)
7-
[![Docs](https://img.shields.io/badge/docs-agentshare.dev-5865F2?style=flat)](https://agentshare.dev/docs)
5+
<h1 align="center">AgentShare MCP Server</h1>
86

9-
## Description
7+
<p align="center">
8+
The data layer for agent commerce — structured price and offer data for AI agents,
9+
over MCP Streamable HTTP and REST.
10+
</p>
1011

11-
**AgentShare** provides **structured marketplace prices and offers for AI agents** via a JSON **REST API** and **MCP** ([Streamable HTTP](https://agentshare.dev/mcp/)). This repository holds **reference Python tool code** (`integrations/mcp_server/`), **GEO/agent docs** (`AGENTS.md`, `llms.txt`, …), and **REST examples**. The live **`/mcp`** implementation and **`.mcpb`** bundle are maintained in **[agent-price-api](https://github.com/anhmtk/agent-price-api)** (`mcpb-bundle/agentshare-price-mcp`).
12-
13-
All MCP tools are **read-only**: they fetch data from the AgentShare API and do not modify your accounts or remote marketplace listings.
14-
15-
### Reviewer quick note (public/private model)
16-
17-
This repository is the **public extension wrapper** used for MCP listing and review.
18-
19-
- **Public repo (`agentshare-mcp`)**: extension-facing artifacts (README/docs/examples, MCP-facing code, support links).
20-
- **Private production backend (`agent-price-api`)**: internal implementation details and operational code.
21-
- **Live runtime endpoint**: `https://agentshare.dev/mcp` (Streamable HTTP).
22-
- **Auth model**: API key (`X-API-Key` or `Authorization: Bearer`) as documented on `agentshare.dev`.
23-
- **Intent**: keep review assets public while protecting private backend internals.
24-
25-
| | |
26-
|---|---|
27-
| **Site & docs** | https://agentshare.dev |
28-
| **MCP endpoint (remote)** | `https://agentshare.dev/mcp/` |
29-
| **Discovery** | [`/agent.json`](https://agentshare.dev/agent.json) · [`/mcp.json`](https://agentshare.dev/mcp.json) · [`llm.txt`](https://agentshare.dev/llm.txt) / [`llms.txt`](https://agentshare.dev/llms.txt) |
12+
<p align="center">
13+
<a href="https://agentshare.dev"><strong>Website</strong></a> ·
14+
<a href="https://agentshare.dev/docs"><strong>Docs</strong></a> ·
15+
<a href="https://agentshare.dev/pricing"><strong>Pricing</strong></a> ·
16+
<a href="https://agentshare.dev/signup"><strong>Get free API key</strong></a>
17+
</p>
3018

3119
---
3220

33-
## For AI agents (machine readable)
21+
## What it does
3422

35-
- **[`AGENTS.md`](AGENTS.md)** — mission, tool names, auth, response envelope, copy-paste MCP JSON, and links to OpenAPI.
36-
- **[`llms.txt`](llms.txt)** — same essentials in a **short, crawl-friendly** single file (for LLM / GEO workflows).
37-
- **[`openapi.json`](openapi.json)** — OpenAPI 3.0 spec for the **REST surface used by this MCP** (`/api/v1/search`, `/offers/*`, `/meta`). The **full** production spec (all routes) is always at **https://agentshare.dev/openapi.json** (single source of truth; no duplicate docs repo).
38-
- **[`mcp-config.json`](mcp-config.json)** — ready-to-paste `mcpServers` block for **`npx mcp-remote`** (Claude Desktop / Cursor) pointing at the remote Streamable HTTP endpoint.
39-
40-
---
23+
Exposes the [AgentShare Price API](https://agentshare.dev) as **four MCP tools** any MCP-compatible client (Claude Desktop, Cursor, Continue.dev, …) can call directly:
4124

42-
## Features
43-
44-
- **`search_products`** — Multi-listing product search with prices, sources, and freshness metadata (`readOnlyHint: true`).
45-
- **`best_offer`** — Single best in-stock-style offer for a product intent (`readOnlyHint: true`).
46-
- **`best_offer_under_budget`** — Best offer under a price ceiling (`readOnlyHint: true`).
47-
- **`service_meta`** — API capabilities and limits; safe for discovery (`readOnlyHint: true`).
48-
- **Official AliExpress integration** on the production API; additional leading marketplaces are added when partnerships and policy allow.
49-
- **Freshness metadata** in responses (e.g. `data_age_seconds`, `freshness_status`) for agent reasoning.
50-
- **Affiliate-ready URLs** where configured; see Terms and Privacy on the site.
51-
52-
---
53-
54-
## Getting an API key
55-
56-
To use MCP or the REST API, you need an API key. Visit [https://agentshare.dev/pricing](https://agentshare.dev/pricing) to get your free tier key (**100 requests / month** on the public free plan at time of writing — always confirm on the site).
57-
58-
---
59-
60-
## Installation
61-
62-
**Recommended — Claude Desktop:** **`.mcpb`** from **[agent-price-api](https://github.com/anhmtk/agent-price-api)** → `mcpb-bundle/agentshare-price-mcp` → `mcpb pack`.
63-
64-
**Cursor / IDE:** Node **`bridge.mjs`** (same as `.mcpb`) or **`npx mcp-remote`** with `--header X-API-Key:…` — see [`mcp-config.json`](mcp-config.json).
65-
66-
**Optional — Python stdio** (this repo), from clone root:
67-
68-
```bash
69-
pip install -r integrations/mcp_server/requirements.txt
70-
export API_KEY=your_api_key
71-
python integrations/mcp_server/server.py
72-
```
73-
74-
Same as `python integrations/mcp_server/run.py`.
75-
76-
**Glama:** use **`integrations/mcp_server/Dockerfile.glama`** (runs `server.py`).
77-
78-
---
79-
80-
## Configuration
81-
82-
### Environment variables
83-
84-
| Variable | Required | Default | Description |
85-
|----------|----------|---------|-------------|
86-
| `API_KEY` | For price tools (REST / some clients) | — | Sent as `X-API-Key` to the API |
87-
| `BASE_URL` | No | `https://agentshare.dev` | API base URL |
88-
89-
---
90-
91-
## Examples
92-
93-
### Example 1: Search for product prices
94-
95-
**User prompt:** “Find me the current price of a Raspberry Pi 5 in Vietnam.”
96-
97-
**Expected behavior:** The assistant uses the **`search_products`** tool. The AgentShare API returns listings from connected sources with prices and freshness metadata.
98-
99-
**Expected output:** A list of offers with source identifier, price (typically in **VND** in API payloads), stock hints when available, and **freshness** fields so the agent can caveat recency.
100-
101-
### Example 2: Best single offer
102-
103-
**User prompt:** “What’s the cheapest NVIDIA Jetson Orin Nano I can buy right now?”
104-
105-
**Expected behavior:** The assistant uses **`best_offer`**. The API returns the single lowest-priced offer the service selects as best, with link and metadata.
106-
107-
**Expected output:** One primary offer: marketplace/source, price, URL, and freshness/stock context where available.
108-
109-
### Example 3: Budget-constrained search
110-
111-
**User prompt:** “I have 2 million VND. Show me the best mini PC I can get.”
112-
113-
**Expected behavior:** The assistant uses **`best_offer_under_budget`** with `max_price=2000000` (VND scale for the deployed API).
25+
| Tool | Returns |
26+
|---|---|
27+
| `search_products` | Multi-source price comparison for a product query |
28+
| `best_offer` | The single cheapest in-stock offer for a query |
29+
| `best_offer_under_budget` | Cheapest offer under a max price |
30+
| `service_meta` | Live coverage, freshness, and pricing metadata |
11431

115-
**Expected output:** The best offer within budget, or a clear **no match** / **out of budget** style result with reasoning fields from the JSON.
32+
Backed by the same JSON contract as `https://agentshare.dev/api/v1/*` — every response includes `freshness_status`, `data_status`, `trust_*` signals so agents can reason about staleness.
11633

11734
---
11835

119-
## Privacy Policy (extension & API use)
120-
121-
This MCP client requires an **AgentShare API key**. For **Claude Desktop Extensions (`.mcpb`)**, the key is stored in **Claude Desktop’s secure storage** and sent only to **https://agentshare.dev** (or your `BASE_URL`) as **`X-API-Key`** for authenticated endpoints.
36+
## Quick install
12237

123-
**Data collection**
38+
### Claude Desktop / Cursor / any Streamable-HTTP MCP client
12439

125-
- This repository’s MCP server **does not** add its own analytics or telemetry beyond what your MCP host provides.
126-
- **Search queries and API parameters** are sent to AgentShare to retrieve results.
127-
- AgentShare may log requests for **rate limiting, billing, abuse prevention, and operations** as described on the site.
40+
Add to your MCP config (e.g. `~/.cursor/mcp.json` or Claude Desktop config):
12841

129-
**Data sharing**
42+
\`\`\`json
43+
{
44+
"mcpServers": {
45+
"agentshare": {
46+
"url": "https://agentshare.dev/mcp",
47+
"headers": {
48+
"X-API-Key": "YOUR_AGENTSHARE_KEY"
49+
}
50+
}
51+
}
52+
}
53+
\`\`\`
13054

131-
- Data is processed by **AgentShare** to fulfill the API request. AgentShare does not sell personal data from the API for marketing. Details are in the full policy below.
55+
Get a free key (100 requests/month, no card): https://agentshare.dev/signup
13256

133-
**Retention & full policy**
57+
### Local stdio (Python)
13458

135-
- Log retention and categories (e.g. API logs) are defined in the **published** privacy policy. **Authoritative text:** **https://agentshare.dev/privacy**
136-
137-
**Terms**
138-
139-
- **https://agentshare.dev/terms**
59+
\`\`\`bash
60+
git clone https://github.com/anhmtk/agentshare-mcp.git
61+
cd agentshare-mcp
62+
pip install -r requirements.txt
63+
export AGENTSHARE_API_KEY=your_key_here
64+
python -m integrations.mcp_server.server
65+
\`\`\`
14066

14167
---
14268

143-
## Support
69+
## Discovery files (for AI search)
14470

145-
- **Issues:** [GitHub Issues](https://github.com/anhmtk/agentshare-mcp/issues)
146-
- **Email:** admin@agentshare.dev
147-
- **Website / docs:** https://agentshare.dev · https://agentshare.dev/docs
148-
149-
---
150-
151-
## Code examples (REST)
152-
153-
The [`examples/`](examples/) folder has small scripts that call the public JSON API (`GET /api/v1/search`, …). Useful for testing a key before wiring MCP.
71+
| URL | Purpose |
72+
|---|---|
73+
| https://agentshare.dev/agent.json | Agent-native discovery manifest |
74+
| https://agentshare.dev/llm.txt | LLM-readable summary |
75+
| https://agentshare.dev/openapi.json | OpenAPI 3 schema |
76+
| https://agentshare.dev/.well-known/mcp.json | MCP endpoint announcement |
77+
| https://agentshare.dev/coverage | Data coverage spec (categories we cover well) |
15478

15579
---
15680

157-
## MCP directories & listings
81+
## Read more
15882

159-
Production discovery (no auth):
160-
161-
| Resource | URL |
162-
|----------|-----|
163-
| `mcp.json` | https://agentshare.dev/mcp.json |
164-
| `agent.json` | https://agentshare.dev/agent.json |
165-
| Server card | https://agentshare.dev/.well-known/mcp/server-card.json |
166-
167-
Third-party indexes (search for **AgentShare** or your listing URL):
168-
169-
- [Smithery](https://smithery.ai/) — MCP server registry
170-
- [Glama](https://glama.ai/) — MCP / AI gateway directory
83+
- 📖 Blog: [Your API ranks on Google. But does it rank for AI agents?](https://dev.to/anhmtk/your-api-ranks-on-google-but-does-it-rank-for-ai-agents-1hg)
84+
- 🧭 Data scope: https://agentshare.dev/coverage — AI hardware, mini PCs, components, robotics, robot/RC power.
85+
- 🛂 Trust + freshness: https://agentshare.dev/docs#data-quality
17186

17287
---
17388

17489
## License
17590

17691
MIT — see [LICENSE](LICENSE).
17792

178-
### Scope (honest & forward-looking)
179-
180-
AgentShare aggregates product and offer data from **connected marketplaces and affiliate sources**. Coverage and freshness vary by source; the API returns **freshness metadata** (e.g. `crawled_at`, `data_age_seconds`, `freshness_status`) so agents can judge reliability.
181-
182-
**Direction:** expand toward **global e‑commerce** as integrations mature. Current product focus: **`GET /coverage`** — https://agentshare.dev/coverage
183-
18493
---
18594

186-
## GitHub — CI & repo traffic
187-
188-
- **CI:** validates MCP package imports on push/PR — **Actions** → **CI**.
189-
- **Traffic:** **Insights → Traffic** (maintainers). Weekly snapshots may be posted to run **Summary** from **github-traffic** workflow.
95+
*Built solo from Vietnam 🇻🇳 by [@anhmtk](https://github.com/anhmtk).*

0 commit comments

Comments
 (0)