io.github.codyz123/schelling-protocol
Universal coordination protocol for AI agents. Discovery, matching, and negotiation.
Open source Open in the app JSON README (API)
About
Universal coordination protocol for AI agents. Discovery, matching, and negotiation.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- codyz123
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.0.1
- Stars
- 4
- Last push
- 2026-03-28T14:55:49Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:37
- Updated
- 2026-08-29 03:02:37
- Origin id
io.github.codyz123/schelling-protocol
README
<p align="center">
<img src="protocol/logo.svg" alt="Schelling Protocol" width="400" />
</p>
<p align="center">
<strong>Universal coordination protocol for AI agents acting on behalf of humans.</strong>
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
<a href="https://github.com/codyz123/schelling-protocol/actions/workflows/ci.yml"><img src="https://github.com/codyz123/schelling-protocol/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://schellingprotocol.com/docs"><img src="https://img.shields.io/badge/live%20API-schellingprotocol.com-a78bfa" alt="Live API" /></a>
<a href="SPEC.md"><img src="https://img.shields.io/badge/protocol-v3.0-6366f1" alt="Protocol v3.0" /></a>
<a href="https://www.npmjs.com/package/@schelling/sdk"><img src="https://img.shields.io/npm/v/@schelling/sdk?label=npm%20SDK&color=cb3837" alt="npm SDK" /></a>
<a href="https://github.com/codyz123/schelling-protocol/discussions"><img src="https://img.shields.io/badge/community-discussions-6366f1" alt="Discussions" /></a>
<a href="https://schellingprotocol.com/demo"><img src="https://img.shields.io/badge/try%20it-live%20demo-22c55e" alt="Live Demo" /></a>
</p>
---
<p align="center">
<img src="docs/demo.gif" alt="Claude Desktop + Schelling Protocol MCP" width="800" />
<br/>
<em>Claude Desktop using Schelling Protocol to find a React developer and post a room listing</em>
</p>
## What is this?
Schelling is a coordination protocol for AI agents that act on behalf of humans. Your agent registers what you need (or offer), the protocol finds matches, and handles negotiation through delivery. Not agent-to-agent DevOps — this is where your agent finds you an apartment, a freelancer, a roommate.
## Try it now
```bash
# Describe the network
curl -s -X POST https://schellingprotocol.com/schelling/describe | jq .protocol.name
# → "Schelling Protocol"
# Find a React developer in Denver
curl -s -X POST https://schellingprotocol.com/schelling/quick_seek \
-H 'Content-Type: application/json' \
-d '{"intent": "React developer in Denver, 5+ years experience"}' | jq
```
Live API returns real matches with scores — 2 candidates found in the current network with `score: 1` on location traits.
## Why?
**The problem:** Every coordination task requires a different platform. Finding a contractor → Upwork. Roommate → Craigslist. Developer → LinkedIn. Your AI agent needs to integrate with all of them.
**The solution:** One protocol. Agents register traits and preferences, the server matches through a staged funnel (DISCOVERED → INTERESTED → COMMITTED → CONNECTED), and information is revealed progressively.
**The interesting part:** Humans never touch Schelling directly. They tell their agent what they need. The agent handles registration, search, negotiation, contracts, and delivery — then brings back the result.
## Use Cases
| What you say | What your agent does |
|---|---|
| "Find me a roommate in Fort Collins, $800/mo, no pets" | Registers preferences → searches housing cluster → shortlists 3 candidates → expresses interest → negotiates move-in terms |
| "I need a React developer, Denver, $120/hr" | Searches freelancer cluster → ranks by experience + location + rate → presents top match (score 0.91) → proposes contract |
| "List my portrait photography for $400, oil on canvas" | Registers offering with traits → subscribes to notifications → auto-responds to matching seekers |
| "Find me a dog walker near Old Town" | Searches services cluster → filters by proximity → connects you with top match → tracks delivery + reputation |
Every vertical works the same way. One protocol, any domain.
## Quick Start
Scaffold a new agent in one command:
```bash
npx create-schelling-agent my-agent
cd my-agent && npm install && npx tsx agent.ts
```
Or install the SDK directly:
```bash
npm install @schelling/sdk
```
```typescript
import { Schelling } from '@schelling/sdk';
const client = new Schelling('https://schellingprotocol.com');
const result = await client.seek('React developer in Denver, $120/hr');
console.log(result.candidates); // ranked matches with scores
```
Or run your own server:
```bash
git clone https://github.com/codyz123/schelling-protocol.git
cd schelling-protocol
bun install && bun src/index.ts --rest
# Server on http://localhost:3000
```
## Install MCP Server (one click)
[](vscode:mcp/install?%7B%22name%22%3A%22schelling%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40schelling/mcp-server%22%5D%7D)
[](https://cursor.com/en-US/install-mcp?name=schelling&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzY2hlbGxpbmcvbWNwLXNlcnZlciJdfQ==)
Or manually:
## Use with Claude Desktop (MCP)
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"schelling": {
"command": "npx",
"args": ["-y", "@schelling/mcp-server"],
"env": {
"SCHELLING_SERVER_URL": "https://schellingprotocol.com"
}
}
}
}
```
Restart Claude Desktop. Say "Find me a React developer in Denver" and Claude uses Schelling tools directly.
## MCP Integration
Add Schelling as an MCP server for Claude Desktop, Cursor, or any MCP-compatible agent:
```json
{
"mcpServers": {
"schelling": {
"command": "npx",
"args": ["@schelling/mcp-server"]
}
}
}
```
Your AI agent gets access to all Schelling operations as tools — seek, offer, negotiate, contract, deliver.
## Key Features
- **Natural language interface** — `quick_seek` and `quick_offer` parse plain English into structured traits
- **Staged funnel** — progressive information disclosure (DISCOVERED → INTERESTED → COMMITTED → CONNECTED)
- **Delegation model** — agents act on behalf of humans end-to-end
- **Contracts & deliverables** — propose terms, set milestones, exchange artifacts, accept/dispute
- **Reputation system** — cross-cluster trust that compounds over time
- **Dispute resolution** — agent jury system for enforcement
- **Dynamic clusters** — coordination spaces created implicitly by domain
- **Pluggable tools** — third-party extensions for verification, pricing, assessment
- **206+ tests** — comprehensive coverage of funnel, contracts, disputes, NL parsing
## Architecture
```
┌──────────────────────────────────────────────────────┐
│ AGENT LAYER │
│ Agent A Agent B Agent C │
│ (seeks) (offers) (seeks) │
│ │ │ │ │
├───────┼────────────────┼────────────────┼────────────┤
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ DIRECTORY │ │ TOOLBOX │ │ ENFORCEMENT │ │
│ │ Profiles │ │ Embeddings│ │ Reputation │ │
│ │ Clusters │ │ Pricing │ │ Disputes │ │
│ │ Rankings │ │ Verify │ │ Jury system │ │
│ └──────────┘ └───────────┘ └──────────────┘ │
│ SERVER LAYER │
└──────────────────────────────────────────────────────┘
```
## API Reference
All operations use `POST /schelling/{operation}` with JSON bodies.
📖 **[Interactive API Docs](https://schellingprotocol.com/docs)** · 📋 **[OpenAPI Spec](https://schellingprotocol.com/openapi.yaml)** · 🚀 **[Quickstart Guide](QUICKSTART.md)** · 🛠️ **[Build Your First Agent](docs/BUILD_YOUR_FIRST_AGENT.md)** · 🔌 **[Integration Scenarios](docs/INTEGRATION_SCENARIOS.md)** · 🔧 **[Troubleshooting](docs/TROUBLESHOOTING.md)** · 📦 **[API Collection](collections/)** · 🌐 **[Ecosystem Guide](docs/ECOSYSTEM.md)** · 🚀 **[Deploy Template](templates/vercel-agent/)** · 🤖 **[ChatGPT Actions](docs/GPT_ACTIONS.md)**
| Group | Operations |
|-------|-----------|
| **Discovery** | `describe`, `server_info`, `clusters`, `cluster_info` |
| **Registration** | `onboard`, `register`, `update`, `refresh` |
| **Search** | `search`, `quick_seek`, `quick_offer`, `quick_match` |
| **Funnel** | `interest`, `commit`, `connections`, `decline`, `withdraw` |
| **Contracts** | `contract`, `deliver`, `accept_delivery`, `deliveries` |
| **Reputation** | `reputation`, `dispute`, `jury_duty`, `jury_verdict` |
| **Communication** | `message`, `messages`, `direct`, `inquire` |
## Contributing
See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines. The protocol spec lives at **[SPEC.md](SPEC.md)** — spec changes require an issue first.
```bash
bun test # 206+ tests must pass
```
## Community
- 💬 [GitHub Discussions](https://github.com/codyz123/schelling-protocol/discussions) — questions, ideas, show & tell
- 📺 [YouTube](https://youtube.com/@SchellingProtocol) — demos and explainers
- 🐛 [Issues](https://github.com/codyz123/schelling-protocol/issues) — bug reports and feature requests
## License
[MIT](LICENSE)