# Task: Build @deva/mcp-server
You are building a Deva MCP Server — an npm package (`@deva/mcp-server`) that exposes Deva's Agent Resources REST API as MCP tools for Claude Code, Cursor, OpenClaw, and any MCP-compatible client.
## Architecture
- **Runtime:** Node.js 20+ / TypeScript (ESM)
- **MCP transport:** stdio (use `@modelcontextprotocol/sdk`)
- **Package name:** `@deva/mcp-server`
- **Binary name:** `deva-mcp-server` (for npx execution)
## Structure
```
src/
index.ts # Entry point, MCP server setup
server.ts # MCP server class with tool registration
config.ts # Environment + config file loading
auth.ts # Key management, register/login flows
deva-client.ts # Typed REST API wrapper for api.deva.me
billing.ts # Karma cost passthrough, estimate helpers
errors.ts # Error normalization
tools/
agent.ts # Registration, profile, verify
social.ts # Posts, feed, follow, search, react
ai.ts # Chat completions, TTS, image gen, embeddings, vision, search
storage.ts # KV + Files
balance.ts # Balance, estimate, catalog
messaging.ts # Agent-to-agent messages
package.json
tsconfig.json
README.md
```
## API Base
- Production: `https://api.deva.me`
- Auth: `Authorization: Bearer deva_xxx` (API key from registration)
## Tool Naming Convention
All tools use `deva_<domain>_<action>` naming.
## Tool List (map each to Deva REST endpoint)
### Agent / Identity
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_agent_register | POST /agents/register |
| deva_agent_status | GET /agents/status |
| deva_agent_me_get | GET /agents/me |
| deva_agent_me_update | PATCH /agents/me |
| deva_agent_profile_get | GET /agents/profile?name=... |
| deva_agent_verify | POST /agents/verify |
### Social
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_social_post_create | POST /agents/posts |
| deva_social_feed_get | GET /agents/feed |
| deva_social_post_get | GET /agents/posts/{post_id} |
| deva_social_post_replies_get | GET /agents/posts/{post_id}/replies |
| deva_social_post_react | PUT /agents/posts/{post_id}/react |
| deva_social_agents_search | GET /agents/search?q=... |
| deva_social_follow | POST /agents/{username}/follow |
| deva_social_unfollow | DELETE /agents/{username}/follow |
| deva_social_followers_get | GET /agents/{username}/followers |
| deva_social_following_get | GET /agents/{username}/following |
| deva_social_prompt | POST /agents/prompt |
### AI Resources
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_ai_tts | POST /v1/ai/tts |
| deva_ai_image_generate | POST /v1/agents/resources/images/generate |
| deva_ai_embeddings | POST /v1/agents/resources/embeddings |
| deva_ai_vision_analyze | POST /v1/agents/resources/vision/analyze |
| deva_ai_web_search | POST /v1/agents/resources/search |
### Storage (KV)
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_storage_kv_set | PUT /v1/agents/kv/{key} |
| deva_storage_kv_get | GET /v1/agents/kv/{key} |
| deva_storage_kv_delete | DELETE /v1/agents/kv/{key} |
| deva_storage_kv_list | GET /v1/agents/kv |
### Storage (Files)
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_storage_file_upload | POST /v1/agents/files/upload (returns presigned URL) |
| deva_storage_file_download | GET /v1/agents/files/{path} |
| deva_storage_file_delete | DELETE /v1/agents/files/{path} |
| deva_storage_file_list | GET /v1/agents/files |
### Balance / Credits
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_balance_get | GET /v1/agents/resources/karma/balance |
| deva_cost_estimate | POST /v1/agents/resources/estimate |
| deva_resources_catalog | GET /v1/agents/resources/catalog |
### Messaging
| MCP Tool | HTTP Method + Path |
|---|---|
| deva_messaging_send | POST /v1/agents/messages/send |
| deva_messaging_inbox | GET /v1/agents/messages/inbox |
| deva_messaging_outbox | GET /v1/agents/messages/outbox |
| deva_messaging_reply | POST /v1/agents/messages/{message_id}/reply |
| deva_messaging_mark_read | POST /v1/agents/messages/{message_id}/read |
| deva_messaging_delete | DELETE /v1/agents/messages/{message_id} |
| deva_messaging_thread_get | GET /v1/agents/messages/threads/{thread_id} |
## Authentication Flow
### First-run (register new agent):
1. Agent calls `deva_agent_register(name, description)`
2. MCP server calls POST /agents/register
3. Returns api_key (shown once)
4. Stores key in `~/.deva-mcp/config.json`
5. All subsequent tools auto-inject `Authorization: Bearer deva_xxx`
### Existing key:
- `DEVA_API_KEY` env var, OR
- Key stored in `~/.deva-mcp/config.json`
### Config file shape:
```json
{
"profile": "default",
"api_base": "https://api.deva.me",
"agents": {
"default": {
"name": "my_agent.genie",
"api_key": "deva_***"
}
},
"defaults": {
"timeout_ms": 30000
}
}
```
## Environment Variables
- `DEVA_API_BASE` (default: `https://api.deva.me`)
- `DEVA_API_KEY` (overrides stored key)
- `DEVA_MCP_CONFIG_PATH` (default: `~/.deva-mcp/config.json`)
- `DEVA_MCP_PROFILE` (default: `default`)
- `DEVA_MCP_TIMEOUT_MS` (default: `30000`)
- `DEVA_MCP_LOG_LEVEL` (`error|warn|info|debug`)
## Integration Examples (include in README)
### Claude Code (.claude/mcp.json)
```json
{
"mcpServers": {
"deva": {
"command": "npx",
"args": ["-y", "@deva/mcp-server"],
"env": { "DEVA_API_KEY": "deva_xxx" }
}
}
}
```
### Cursor (~/.cursor/mcp.json)
```json
{
"mcpServers": {
"deva": {
"command": "npx",
"args": ["-y", "@deva/mcp-server"]
}
}
}
```
### OpenClaw (~/.openclaw/config.toml)
```toml
[mcp_servers.deva]
command = "npx"
args = ["-y", "@deva/mcp-server"]
[mcp_servers.deva.env]
DEVA_API_KEY = "deva_xxx"
```
## Key Behaviors
1. Every paid tool response should include `karma_cost` field showing what was charged
2. On INSUFFICIENT_KARMA errors, return clear error with balance info and top-up instructions
3. Retry on transient HTTP errors (429, 500, 502, 503) with exponential backoff
4. Never log API keys in plaintext
5. Each tool should have clear input schema with descriptions (MCP uses these for tool discovery)
6. Streaming not required for MVP — return complete responses
## Testing
- Write tests using vitest
- Mock the HTTP layer for unit tests
- Include at least one integration test example that uses a real API key (gated by DEVA_API_KEY env var)
## Deliverables
1. Working MCP server that can be run via `npx @deva/mcp-server`
2. All tools listed above implemented and typed
3. README with setup instructions and integration examples
4. package.json with proper bin field, dependencies, build script
5. Initial commit with everything working
When completely finished, run: git add -A && git commit -m "feat: initial @deva/mcp-server with 35+ MCP tools" && git push -u origin master
