Skip to content

Commit 088cf60

Browse files
ptrstnptrstn
committed
Add mcp.md to documentation for aas-mcp integration
1 parent 4aa99fe commit 088cf60

File tree

2 files changed

+149
-1
lines changed

2 files changed

+149
-1
lines changed

‎docs/mcp.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# 🤖 MCP Integration
2+
3+
**aas-mcp** provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to interact with Asset Administration Shells through the Shellsmith ecosystem.
4+
5+
---
6+
7+
## What is MCP?
8+
9+
The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external data sources and tools. It allows AI models to securely access and interact with various services, databases, and APIs through a standardized interface.
10+
11+
MCP servers expose capabilities as **tools** that AI assistants can invoke to perform specific tasks, like querying databases, calling APIs, or managing resources.
12+
13+
---
14+
15+
## Installation
16+
17+
**aas-mcp** is automatically installed when you install Shellsmith with the optional `mcp` dependency `shellsmith[mcp]`.
18+
You can also install **aas-mcp** independently:
19+
20+
```bash
21+
pip install aas-mcp
22+
```
23+
24+
---
25+
26+
## MCP Client Configuration
27+
28+
### Claude Desktop
29+
30+
Add **aas-mcp** to your Claude Desktop configuration file:
31+
32+
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
33+
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
34+
35+
```json
36+
{
37+
"mcpServers": {
38+
"aas-mcp": {
39+
"command": "aas-mcp",
40+
"env": {
41+
"SHELLSMITH_BASYX_ENV_HOST": "http://localhost:8081"
42+
}
43+
}
44+
}
45+
}
46+
```
47+
48+
### Other MCP Clients
49+
50+
The configuration format is similar for other MCP-compatible clients like [LM Studio](https://lmstudio.ai/), [Continue](https://continue.dev/), or custom MCP implementations.
51+
52+
Consult your client's documentation for the specific configuration syntax.
53+
54+
---
55+
56+
## BaSyx Environment Configuration
57+
58+
The MCP server connects to an Eclipse BaSyx environment. Configure the connection using:
59+
60+
### Environment Variable
61+
62+
```bash
63+
export SHELLSMITH_BASYX_ENV_HOST=https://your-basyx-host:8081
64+
```
65+
66+
### `.env` File
67+
68+
Create a `.env` file in your working directory:
69+
70+
```dotenv
71+
SHELLSMITH_BASYX_ENV_HOST=https://your-basyx-host:8081
72+
```
73+
74+
### Dynamic Configuration
75+
76+
Each MCP tool accepts an optional `host` parameter to override the default configuration on a per-request basis.
77+
78+
---
79+
80+
## Available MCP Tools
81+
82+
The **aas-mcp** server exposes 25+ tools for comprehensive AAS management:
83+
84+
### Shell Management
85+
86+
| Tool | Description |
87+
|----------------|----------------------------------------------------|
88+
| `get_shells` | Retrieve all available Asset Administration Shells |
89+
| `get_shell` | Get a specific Shell by its identifier |
90+
| `create_shell` | Create a new Asset Administration Shell |
91+
| `update_shell` | Update an existing Shell (full replacement) |
92+
| `delete_shell` | Delete a Shell and optionally its Submodels |
93+
94+
### Submodel Management
95+
96+
| Tool | Description |
97+
|-------------------------|-----------------------------------------------------|
98+
| `get_submodels` | Retrieve all available Submodels |
99+
| `get_submodel` | Get a specific Submodel by its identifier |
100+
| `create_submodel` | Create a new Submodel |
101+
| `update_submodel` | Update an existing Submodel (full replacement) |
102+
| `delete_submodel` | Delete a Submodel and optionally unlink from Shells |
103+
| `get_submodel_value` | Get the raw `$value` of a Submodel |
104+
| `update_submodel_value` | Update the `$value` of a Submodel (partial update) |
105+
| `get_submodel_metadata` | Get the `$metadata` of a Submodel |
106+
107+
### Submodel Element Management
108+
109+
| Tool | Description |
110+
|---------------------------------|----------------------------------------------------|
111+
| `get_submodel_elements` | Get all elements from a Submodel |
112+
| `get_submodel_element` | Get a specific element by its path |
113+
| `create_submodel_element` | Create a new Submodel Element |
114+
| `update_submodel_element` | Update an existing element (full replacement) |
115+
| `delete_submodel_element` | Delete a Submodel Element |
116+
| `get_submodel_element_value` | Get the raw `$value` of a Submodel Element |
117+
| `update_submodel_element_value` | Update the `$value` of an element (partial update) |
118+
119+
### Reference Management
120+
121+
| Tool | Description |
122+
|-----------------------|------------------------------------------|
123+
| `get_submodel_refs` | Get all Submodel references from a Shell |
124+
| `create_submodel_ref` | Create a Submodel reference in a Shell |
125+
| `delete_submodel_ref` | Remove a Submodel reference from a Shell |
126+
127+
### Health & Monitoring
128+
129+
| Tool | Description |
130+
|---------------------|--------------------------------------------------|
131+
| `get_health_status` | Check the health status of the BaSyx environment |
132+
| `is_healthy` | Boolean check for environment health |
133+
134+
---
135+
136+
## Starting the Server
137+
138+
Run the MCP server directly:
139+
140+
```bash
141+
aas-mcp
142+
```
143+
144+
The server runs in **stdio mode** by default. It will listen for MCP requests and respond with tool results.
145+
146+
!!! note
147+
The server typically runs as a background process managed by your MCP client (like Claude Desktop).

‎mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,9 @@ theme:
3636

3737
nav:
3838
- Home: index.md
39-
- CLI: cli.md
4039
- API: api.md
40+
- CLI: cli.md
41+
- MCP: mcp.md
4142
- Contributing: contributing.md
4243

4344
markdown_extensions:

0 commit comments

Comments
 (0)