Skip to content

Commit c2a735d

Browse files
respencer-nclclaude
respencer-ncl
and
claude
committed
Add MCP section with AI tool integration guides
New section for RIDDL MCP Server documentation: - Main overview page with capabilities and tools - Claude Desktop configuration guide - Claude Code CLI configuration guide - Gemini CLI configuration guide - VS Code Copilot configuration guide - IntelliJ AI Assistant configuration guide - IntelliJ Junie configuration guide Includes authentication docs, protocol details, and placeholder for public server URL. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent d4bd9f2 commit c2a735d

7 files changed

Lines changed: 1480 additions & 0 deletions

File tree

‎docs/MCP/claude-code.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Claude Code Configuration
2+
3+
This guide explains how to configure Claude Code (Anthropic's CLI tool) to
4+
use the RIDDL MCP Server for AI-assisted domain modeling.
5+
6+
## Prerequisites
7+
8+
- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
9+
- API key for the RIDDL MCP Server (contact support@ossuminc.com)
10+
11+
## Configuration
12+
13+
Claude Code uses a JSON settings file for MCP server configuration.
14+
15+
### Configuration File Location
16+
17+
| Platform | Path |
18+
|----------|------|
19+
| **macOS** | `~/.claude/settings.json` |
20+
| **Windows** | `%USERPROFILE%\.claude\settings.json` |
21+
| **Linux** | `~/.claude/settings.json` |
22+
23+
### Adding the RIDDL MCP Server
24+
25+
Edit your settings file to add the RIDDL server under `mcpServers`:
26+
27+
```json
28+
{
29+
"mcpServers": {
30+
"riddl": {
31+
"url": "{{MCP_SERVER_URL}}/mcp/v1",
32+
"headers": {
33+
"X-API-KEY": "your-api-key"
34+
}
35+
}
36+
}
37+
}
38+
```
39+
40+
!!! warning "Replace Placeholders"
41+
- Replace `{{MCP_SERVER_URL}}` with the actual server URL when available
42+
- Replace `your-api-key` with your actual API key
43+
44+
### Project-Level Configuration
45+
46+
You can also configure the RIDDL MCP server for a specific project by
47+
creating a `.claude/settings.json` file in your project root:
48+
49+
```json
50+
{
51+
"mcpServers": {
52+
"riddl": {
53+
"url": "{{MCP_SERVER_URL}}/mcp/v1",
54+
"headers": {
55+
"X-API-KEY": "your-api-key"
56+
}
57+
}
58+
}
59+
}
60+
```
61+
62+
Project-level settings merge with user-level settings, with project
63+
settings taking precedence.
64+
65+
### Using a Local Server
66+
67+
For development with a locally running server:
68+
69+
```json
70+
{
71+
"mcpServers": {
72+
"riddl": {
73+
"url": "http://localhost:8080/mcp/v1",
74+
"headers": {
75+
"X-API-KEY": "your-local-api-key"
76+
}
77+
}
78+
}
79+
}
80+
```
81+
82+
## Verify Connection
83+
84+
Start Claude Code and ask it to test the connection:
85+
86+
```bash
87+
claude
88+
```
89+
90+
Then in the session:
91+
92+
> "Can you validate this RIDDL: `domain Test is { }`"
93+
94+
Claude should use the `validate-text` tool and return results.
95+
96+
## Usage Examples
97+
98+
### Validating RIDDL Files
99+
100+
When working in a directory with `.riddl` files:
101+
102+
> "Please validate the file src/domain.riddl"
103+
104+
Claude Code can read the file and use the RIDDL MCP server to validate it.
105+
106+
### Creating New Models
107+
108+
> "Help me create a RIDDL model for a hotel reservation system with
109+
> bookings, rooms, and guests"
110+
111+
Claude will use `map-domain-to-riddl` to suggest a structure, then help
112+
you refine it.
113+
114+
### Fixing Validation Errors
115+
116+
> "I'm getting validation errors in my RIDDL file. Can you explain them
117+
> and suggest fixes?"
118+
119+
Claude will use `validate-text` and `explain-error` to help you resolve
120+
issues.
121+
122+
### Checking Model Quality
123+
124+
> "Check if my order management model is complete enough for simulation"
125+
126+
Claude will use `check-completeness` and `check-simulability` to analyze
127+
your model.
128+
129+
## Workflow Integration
130+
131+
### With Git Repositories
132+
133+
Claude Code works well with RIDDL projects under version control:
134+
135+
```bash
136+
cd my-riddl-project
137+
claude
138+
```
139+
140+
> "Review all the .riddl files in this project and create a summary of
141+
> the domain model"
142+
143+
### Continuous Validation
144+
145+
As you edit RIDDL files, ask Claude to validate your changes:
146+
147+
> "I just updated src/contexts/orders.riddl - can you validate it?"
148+
149+
### Documentation Generation
150+
151+
> "Generate documentation for the entity definitions in this model"
152+
153+
## Troubleshooting
154+
155+
### Server Not Connecting
156+
157+
- Test the server directly: `curl {{MCP_SERVER_URL}}/health`
158+
- Verify JSON syntax in settings file
159+
- Check that the URL doesn't have trailing slashes
160+
161+
### Authentication Errors
162+
163+
- Verify API key is correct
164+
- Check for accidental whitespace in the key
165+
- Ensure headers are properly formatted in JSON
166+
167+
### Tools Not Available
168+
169+
- Restart Claude Code after configuration changes
170+
- Check the MCP server logs for connection attempts
171+
- Verify the `mcpServers` object exists in settings
172+
173+
## Available RIDDL Tools
174+
175+
| Tool | Use Case |
176+
|------|----------|
177+
| `validate-text` | Check RIDDL source for errors |
178+
| `validate-url` | Validate RIDDL from GitHub URLs |
179+
| `validate-partial` | Check incomplete/in-progress models |
180+
| `check-completeness` | Find missing elements |
181+
| `check-simulability` | Verify simulation readiness |
182+
| `map-domain-to-riddl` | Convert descriptions to RIDDL |
183+
| `explain-error` | Understand validation errors |
184+
| `suggest-next` | Get recommendations for next steps |
185+
186+
## Tips for Effective Use
187+
188+
1. **Be specific**: Instead of "validate my code", say "validate the
189+
Order entity in src/orders.riddl"
190+
191+
2. **Provide context**: Share relevant parts of your model when asking
192+
questions
193+
194+
3. **Iterate**: Use `suggest-next` to build models incrementally
195+
196+
4. **Learn from errors**: Ask Claude to explain any validation errors
197+
you encounter
198+
199+
---
200+
201+
[Back to MCP Overview](./index.md)

‎docs/MCP/claude-desktop.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Claude Desktop Configuration
2+
3+
This guide explains how to configure Claude Desktop to use the RIDDL MCP
4+
Server for AI-assisted domain modeling.
5+
6+
## Prerequisites
7+
8+
- Claude Desktop application installed
9+
- API key for the RIDDL MCP Server (contact support@ossuminc.com)
10+
11+
## Configuration
12+
13+
Claude Desktop uses a JSON configuration file to define MCP servers.
14+
15+
### Configuration File Location
16+
17+
| Platform | Path |
18+
|----------|------|
19+
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
20+
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
21+
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
22+
23+
### Adding the RIDDL MCP Server
24+
25+
Edit your configuration file to add the RIDDL server:
26+
27+
```json
28+
{
29+
"mcpServers": {
30+
"riddl": {
31+
"url": "{{MCP_SERVER_URL}}/mcp/v1",
32+
"headers": {
33+
"X-API-KEY": "your-api-key"
34+
}
35+
}
36+
}
37+
}
38+
```
39+
40+
!!! warning "Replace Placeholders"
41+
- Replace `{{MCP_SERVER_URL}}` with the actual server URL when available
42+
- Replace `your-api-key` with your actual API key
43+
44+
### Complete Example
45+
46+
If you have other MCP servers configured, add RIDDL alongside them:
47+
48+
```json
49+
{
50+
"mcpServers": {
51+
"riddl": {
52+
"url": "{{MCP_SERVER_URL}}/mcp/v1",
53+
"headers": {
54+
"X-API-KEY": "your-api-key"
55+
}
56+
},
57+
"filesystem": {
58+
"command": "npx",
59+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
60+
}
61+
}
62+
}
63+
```
64+
65+
### Using a Local Server
66+
67+
For development with a locally running server:
68+
69+
```json
70+
{
71+
"mcpServers": {
72+
"riddl": {
73+
"url": "http://localhost:8080/mcp/v1",
74+
"headers": {
75+
"X-API-KEY": "your-local-api-key"
76+
}
77+
}
78+
}
79+
}
80+
```
81+
82+
## Restart Claude Desktop
83+
84+
After modifying the configuration:
85+
86+
1. Quit Claude Desktop completely
87+
2. Relaunch Claude Desktop
88+
3. The RIDDL tools should now be available
89+
90+
## Verify Connection
91+
92+
Ask Claude to verify the connection:
93+
94+
> "Can you validate this RIDDL code for me?"
95+
> ```riddl
96+
> domain Example is { }
97+
> ```
98+
99+
Claude should use the `validate-text` tool and return validation results.
100+
101+
## Usage Examples
102+
103+
### Validate RIDDL Code
104+
105+
> "Please validate this RIDDL model and explain any errors:"
106+
> ```riddl
107+
> domain OrderManagement is {
108+
> context Orders is {
109+
> entity Order is { }
110+
> }
111+
> }
112+
> ```
113+
114+
### Check Completeness
115+
116+
> "Analyze this model for completeness and tell me what's missing:"
117+
> ```riddl
118+
> domain Inventory is {
119+
> context Warehouse is {
120+
> type ProductId is Id(Product)
121+
> }
122+
> }
123+
> ```
124+
125+
### Convert Natural Language
126+
127+
> "I need to model an e-commerce system with shopping carts, orders, and
128+
> inventory tracking. What RIDDL structure would you suggest?"
129+
130+
### Explain Errors
131+
132+
> "I got this error: 'Undefined reference to type CustomerID'. What does
133+
> this mean and how do I fix it?"
134+
135+
## Troubleshooting
136+
137+
### Server Not Connecting
138+
139+
- Verify the URL is correct and accessible
140+
- Check that your API key is valid
141+
- Ensure the server is running (test with `curl {{MCP_SERVER_URL}}/health`)
142+
143+
### Tools Not Appearing
144+
145+
- Restart Claude Desktop after configuration changes
146+
- Check for JSON syntax errors in the configuration file
147+
- Verify the `mcpServers` key is at the top level of the JSON
148+
149+
### Authentication Errors
150+
151+
- Verify your API key is correctly entered
152+
- Check for extra spaces or quotes around the key
153+
- Contact support@ossuminc.com if issues persist
154+
155+
## Available RIDDL Tools in Claude
156+
157+
Once connected, Claude can use these tools:
158+
159+
| Tool | Ask Claude To... |
160+
|------|-----------------|
161+
| `validate-text` | "Validate this RIDDL code" |
162+
| `validate-partial` | "Check this incomplete model" |
163+
| `check-completeness` | "What's missing from this model?" |
164+
| `check-simulability` | "Can this model be simulated?" |
165+
| `map-domain-to-riddl` | "Convert this description to RIDDL" |
166+
| `explain-error` | "Explain this error message" |
167+
| `suggest-next` | "What should I add next?" |
168+
169+
---
170+
171+
[Back to MCP Overview](./index.md)

0 commit comments

Comments
 (0)