Skip to content

Commit 45c0479

Browse files
dadadadas111dadadadas111
committed
fix: resources
1 parent ae0d060 commit 45c0479

File tree

13 files changed

+2057
-57
lines changed

13 files changed

+2057
-57
lines changed

‎TESTING_RESOURCES.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# How to Test MCP Resources
2+
3+
## Prerequisites
4+
5+
1. Your MCP server should be running on `http://localhost:3001`
6+
2. You need:
7+
- A valid project API key (e.g., `test-project`)
8+
- A valid JWT Bearer token
9+
10+
## Testing with cURL
11+
12+
### 1. Test resources/list
13+
14+
```bash
15+
curl -X POST http://localhost:3001/mcp/YOUR_PROJECT_KEY \
16+
-H "Content-Type: application/json" \
17+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
18+
-d '{
19+
"jsonrpc": "2.0",
20+
"id": 1,
21+
"method": "resources/list",
22+
"params": {}
23+
}'
24+
```
25+
26+
Expected response:
27+
28+
```json
29+
{
30+
"jsonrpc": "2.0",
31+
"id": 1,
32+
"result": {
33+
"resources": [
34+
{
35+
"uri": "rogo://docs/device-attributes",
36+
"name": "Device Attributes Reference",
37+
"description": "Complete reference of device attributes...",
38+
"mimeType": "text/markdown"
39+
},
40+
{
41+
"uri": "rogo://docs/control-guide",
42+
"name": "Device Control Guide",
43+
"description": "How to control devices...",
44+
"mimeType": "text/markdown"
45+
},
46+
{
47+
"uri": "rogo://docs/state-guide",
48+
"name": "Device State Guide",
49+
"description": "How to read device state...",
50+
"mimeType": "text/markdown"
51+
}
52+
]
53+
}
54+
}
55+
```
56+
57+
### 2. Test resources/read
58+
59+
```bash
60+
# Read device attributes
61+
curl -X POST http://localhost:3001/mcp/YOUR_PROJECT_KEY \
62+
-H "Content-Type: application/json" \
63+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
64+
-d '{
65+
"jsonrpc": "2.0",
66+
"id": 2,
67+
"method": "resources/read",
68+
"params": {
69+
"uri": "rogo://docs/device-attributes"
70+
}
71+
}'
72+
73+
# Read control guide
74+
curl -X POST http://localhost:3001/mcp/YOUR_PROJECT_KEY \
75+
-H "Content-Type: application/json" \
76+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
77+
-d '{
78+
"jsonrpc": "2.0",
79+
"id": 3,
80+
"method": "resources/read",
81+
"params": {
82+
"uri": "rogo://docs/control-guide"
83+
}
84+
}'
85+
86+
# Read state guide
87+
curl -X POST http://localhost:3001/mcp/YOUR_PROJECT_KEY \
88+
-H "Content-Type: application/json" \
89+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
90+
-d '{
91+
"jsonrpc": "2.0",
92+
"id": 4,
93+
"method": "resources/read",
94+
"params": {
95+
"uri": "rogo://docs/state-guide"
96+
}
97+
}'
98+
```
99+
100+
Expected response:
101+
102+
```json
103+
{
104+
"jsonrpc": "2.0",
105+
"id": 2,
106+
"result": {
107+
"contents": [
108+
{
109+
"uri": "rogo://docs/device-attributes",
110+
"mimeType": "text/markdown",
111+
"text": "# Device Attributes Reference\n\n..."
112+
}
113+
]
114+
}
115+
}
116+
```
117+
118+
## What to Look For in Server Logs
119+
120+
When resources are accessed, you should see:
121+
122+
```
123+
[Nest] LOG [McpController] MCP request received - Project: test-project, Method: resources/list
124+
[Nest] LOG [McpProtocolHandlerService] Client initialize request received
125+
[Nest] LOG [McpProtocolHandlerService] 📋 Resources list requested
126+
[Nest] LOG [McpProtocolHandlerService] Returning 3 registered resources
127+
128+
[Nest] LOG [McpController] MCP request received - Project: test-project, Method: resources/read
129+
[Nest] LOG [McpProtocolHandlerService] 📖 Resource read requested: rogo://docs/device-attributes
130+
[Nest] LOG [McpProtocolHandlerService] Reading resource: Device Attributes Reference
131+
[Nest] LOG [ResourceRegistryService] 🔍 [RESOURCE ACCESS] device-attributes resource read requested
132+
[Nest] LOG [ResourceRegistryService] ✅ [RESOURCE ACCESS] device-attributes resource read successful (12345 chars)
133+
[Nest] LOG [McpProtocolHandlerService] ✅ Resource read successful: rogo://docs/device-attributes (12345 chars)
134+
```
135+
136+
## Testing with MCP Client SDK
137+
138+
If you want to use the TypeScript SDK (requires `npx tsx` or similar):
139+
140+
```typescript
141+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
142+
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamablehttp.js';
143+
144+
const transport = new StreamableHTTPClientTransport(
145+
new URL('http://localhost:3001/mcp/YOUR_PROJECT_KEY'),
146+
);
147+
148+
const client = new Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {} });
149+
150+
await client.connect(transport);
151+
152+
// List resources
153+
const list = await client.listResources();
154+
console.log('Resources:', list.resources);
155+
156+
// Read a resource
157+
const content = await client.readResource({
158+
uri: 'rogo://docs/device-attributes',
159+
});
160+
console.log('Content:', content.contents[0].text);
161+
162+
await client.close();
163+
```
164+
165+
## Verification Checklist
166+
167+
- [ ] Server starts without errors
168+
- [ ] `resources/list` returns 3 resources
169+
- [ ] Each resource has correct URI, name, description, mimeType
170+
- [ ] `resources/read` returns markdown content
171+
- [ ] Server logs show resource access with 🔍 and ✅ emojis
172+
- [ ] Resource content length is logged
173+
- [ ] No errors in server console

‎docs/ai-resources/README.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# AI-Optimized Resource Documentation
2+
3+
This directory contains simplified, AI-friendly documentation for the IoT Cloud MCP Bridge.
4+
5+
## Purpose
6+
7+
These documents are designed specifically for **AI agents** (LLMs) to:
8+
9+
- ✅ Understand device control concepts quickly
10+
- ✅ Find exact command formats easily
11+
- ✅ Follow clear step-by-step workflows
12+
- ✅ Avoid common mistakes
13+
14+
## Files
15+
16+
### 1. `overview.md` (433 lines)
17+
18+
**Introduction to the IoT Cloud MCP Bridge**
19+
20+
**Contains:**
21+
22+
- System architecture overview
23+
- Core concepts (device, element, attribute, state)
24+
- Field definitions (uuid, elementIds, command)
25+
- Available MCP tools
26+
- Common patterns and workflows
27+
- Glossary of terms
28+
- Quick reference card
29+
30+
**Use when:** First time using the system, need to understand fundamental concepts
31+
32+
---
33+
34+
### 2. `device-attributes.md` (253 lines)
35+
36+
**Complete reference of device attributes and commands**
37+
38+
**Contains:**
39+
40+
- Quick reference table of common attributes
41+
- Device-type-specific sections (lights, switches, AC, etc.)
42+
- Command format examples with explanations
43+
- Value ranges and meanings
44+
- IR remote button codes
45+
- Do's and Don'ts for AI agents
46+
47+
**Use when:** You need to know WHAT commands are available and their formats
48+
49+
---
50+
51+
### 3. `control-guide.md` (382 lines)
52+
53+
**Step-by-step guide for controlling devices**
54+
55+
**Contains:**
56+
57+
- 2 control options (simple actions vs direct commands)
58+
- Step-by-step workflow
59+
- Multi-element device control
60+
- Common patterns and examples
61+
- Timing considerations
62+
- Troubleshooting guide
63+
64+
**Use when:** You need to know HOW to control a device (workflow)
65+
66+
---
67+
68+
### 4. `state-guide.md` (435 lines)
69+
70+
**Complete guide to reading and interpreting device state**
71+
72+
**Contains:**
73+
74+
- State structure explanation with visual examples
75+
- 5+ real device examples (lights, switches, multi-element, AC)
76+
- How to use state in code (verification, capability discovery)
77+
- State array format details
78+
- Common attribute ID reference table
79+
- Full annotated examples
80+
81+
**Use when:** You need to READ device state or verify control commands worked
82+
83+
---
84+
85+
## Key Improvements Over Original Docs
86+
87+
### Before (Original Docs)
88+
89+
- ❌ Mixed Vietnamese and English
90+
- ❌ CSV format hard to parse
91+
- ❌ Technical API documentation style
92+
- ❌ Scattered information
93+
- ❌ No AI-specific guidance
94+
95+
### After (AI-Optimized Docs)
96+
97+
- ✅ 100% English, clear language
98+
- ✅ Structured markdown with examples
99+
- ✅ Tutorial/guide style with clear explanations
100+
- ✅ Organized by use case
101+
- ✅ Explicit AI agent guidance (Do's/Don'ts, decision trees)
102+
- ✅ Real-world examples with annotations
103+
- ✅ Quick reference sections for fast lookup
104+
105+
---
106+
107+
## How AI Agents Should Use These Resources
108+
109+
### Recommended Reading Order
110+
111+
**1. First Time Using the MCP:**
112+
Read in this order:
113+
114+
1. `overview.md` - Core concepts and what you can do
115+
2. `device-attributes.md` - Available commands and device types
116+
3. `control-guide.md` - Control workflows
117+
4. `state-guide.md` - Read and verify state
118+
119+
**2. When Controlling a Device:**
120+
121+
1. Read `control-guide.md` → Choose simple or advanced control
122+
2. Reference `device-attributes.md` → Find command format
123+
3. Reference `state-guide.md` → Verify command worked
124+
125+
**3. Quick Reference:**
126+
127+
- Need a command format? → `device-attributes.md` Quick Reference table
128+
- Forgot the workflow? → `control-guide.md` Summary Checklist
129+
- How to read state? → `state-guide.md` Quick Reference section
130+
131+
---
132+
133+
## Integration with MCP
134+
135+
These files are exposed as MCP resources:
136+
137+
```typescript
138+
// List all resources
139+
resources/list
140+
141+
// Read specific resource
142+
resources/read { uri: "rogo://docs/overview" }
143+
resources/read { uri: "rogo://docs/device-attributes" }
144+
resources/read { uri: "rogo://docs/control-guide" }
145+
resources/read { uri: "rogo://docs/state-guide" }
146+
```
147+
148+
**Resource URIs:**
149+
150+
- `rogo://docs/overview` → `overview.md`
151+
- `rogo://docs/device-attributes` → `device-attributes.md`
152+
- `rogo://docs/control-guide` → `control-guide.md`
153+
- `rogo://docs/state-guide` → `state-guide.md`
154+
155+
---
156+
157+
## Content Principles
158+
159+
All documentation follows these principles:
160+
161+
### ✅ AI-Friendly Writing
162+
163+
- Clear, direct language
164+
- Active voice
165+
- Short sentences and paragraphs
166+
- Concrete examples over abstract concepts
167+
168+
### ✅ Actionable Content
169+
170+
- Every section answers "what do I do?"
171+
- Step-by-step instructions
172+
- Copy-paste-ready code examples
173+
- Decision trees and checklists
174+
175+
### ✅ Complete Coverage
176+
177+
- No assumed knowledge
178+
- All edge cases explained
179+
- Error scenarios included
180+
- Verification steps mandatory
181+
182+
### ✅ Structured Format
183+
184+
- Consistent heading hierarchy
185+
- Visual separators (---) between major sections
186+
- Code blocks with syntax highlighting
187+
- Tables for quick reference
188+
189+
---
190+
191+
## Maintenance
192+
193+
When updating these docs:
194+
195+
1. **Keep it simple** - AI agents prefer clear over clever
196+
2. **Add examples** - Every new concept needs a working example
197+
3. **Update all three** - If you change device behavior, update relevant sections in all files
198+
4. **Test with real AI** - Have an LLM read it and try to follow the instructions
199+
200+
**Files to update:**
201+
202+
- Source: `docs/ai-resources/*.md`
203+
- Resource definitions: `src/resources/definitions/*.resource.ts` (already point to these files)
204+
205+
---
206+
207+
## Statistics
208+
209+
- **Total Lines**: 1,502 lines of AI-optimized documentation
210+
- **overview.md**: 433 lines (29%)
211+
- **device-attributes.md**: 252 lines (17%)
212+
- **control-guide.md**: 382 lines (25%)
213+
- **state-guide.md**: 435 lines (29%)
214+
215+
**Coverage:**
216+
217+
- 4 comprehensive guides (overview + 3 specialized guides)
218+
- 8 device types documented
219+
- 30+ attribute IDs explained
220+
- 20+ workflow examples
221+
- 100% MCP tool coverage

0 commit comments

Comments
 (0)