# MCP Services Reference
## Overview
The ADL (Architectural Decision Log) MCP Server provides tools for managing architectural decisions through the Model Context Protocol. All services interact with a GraphQL backend.
## Available MCP Tools
| Tool Name | Description | Required Parameters | Optional Parameters | Return Type |
|-----------|-------------|-------------------|-------------------|-------------|
| `adl_list` | List all architectural decision log entries | None | None | Array of ADL entries (JSON) |
| `adl_get` | Get a specific ADL entry by ID | `id` (string) | None | Single ADL entry (JSON) or error |
| `adl_create` | Create a new architectural decision log entry | `author` (string)<br>`title` (string)<br>`decision` (string)<br>`factSheets` (array of strings)<br>`status` (enum: Proposed/Approved) | None | Created ADL entry (JSON) |
| `adl_update` | Update an existing ADL entry | `id` (string) | `author` (string)<br>`title` (string)<br>`decision` (string)<br>`factSheets` (array of strings)<br>`status` (enum: Proposed/Approved) | Updated ADL entry (JSON) |
| `adl_delete` | Delete an ADL entry by ID | `id` (string) | None | Success message or error |
| `adl_search` | Search for ADL entries by substring matching | None | `author` (string)<br>`title` (string)<br>`decision` (string)<br>`factSheets` (string)<br>`status` (enum: Proposed/Approved) | Array of matching ADL entries (JSON) |
## Data Structures
### ADL Entry Object
```json
{
"id": "string (UUID)",
"created": "string (ISO 8601 timestamp)",
"lastEdited": "string (ISO 8601 timestamp)",
"author": "string",
"title": "string",
"decision": "string",
"factSheets": ["string", "string"],
"status": "Proposed | Approved"
}
```
## Detailed Service Specifications
### 1. adl_list
**Purpose:** Retrieve all ADL entries from the system
**Input:**
- No parameters required
**Output:**
```json
[
{
"id": "uuid-v4",
"created": "2026-01-23T10:00:00.000Z",
"lastEdited": "2026-01-23T10:00:00.000Z",
"author": "John Doe",
"title": "Migration to Microservices",
"decision": "Detailed decision description...",
"factSheets": ["Customer Service", "Order Management"],
"status": "Approved"
}
]
```
**Use Cases:**
- View all architectural decisions
- Generate reports
- Search/filter decisions (client-side)
---
### 2. adl_get
**Purpose:** Retrieve a specific ADL entry by its unique identifier
**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✅ Yes | The unique UUID of the ADL entry |
**Output:**
- **Success:** Returns the ADL entry object (see Data Structures above)
- **Error:** Returns error message if entry not found
**Use Cases:**
- View decision details
- Link to specific decisions
- Retrieve decision for editing
---
### 3. adl_create
**Purpose:** Create a new architectural decision log entry
**Input:**
| Parameter | Type | Required | Description | Constraints |
|-----------|------|----------|-------------|-------------|
| `author` | string | ✅ Yes | Name of the person making the decision | Non-empty string |
| `title` | string | ✅ Yes | Brief title of the decision | Non-empty string |
| `decision` | string | ✅ Yes | Detailed description of the architectural decision | Non-empty string |
| `factSheets` | array[string] | ✅ Yes | List of related SAP/LeanIX Fact Sheet names | Array of strings |
| `status` | enum | ✅ Yes | Status of the decision | Must be "Proposed" or "Approved" |
**Output:**
```json
{
"id": "generated-uuid-v4",
"created": "auto-generated-timestamp",
"lastEdited": "auto-generated-timestamp",
"author": "provided-author",
"title": "provided-title",
"decision": "provided-decision",
"factSheets": ["provided", "fact", "sheets"],
"status": "provided-status"
}
```
**Auto-Generated Fields:**
- `id`: Automatically generated UUID v4
- `created`: Current timestamp (ISO 8601)
- `lastEdited`: Current timestamp (ISO 8601)
**Use Cases:**
- Document new architectural decisions
- Propose architectural changes
- Record approved decisions
---
### 4. adl_update
**Purpose:** Update an existing ADL entry (partial updates supported)
**Input:**
| Parameter | Type | Required | Description | Notes |
|-----------|------|----------|-------------|-------|
| `id` | string | ✅ Yes | The unique UUID of the ADL entry to update | Must exist |
| `author` | string | ❌ No | Updated author name | Only if changing |
| `title` | string | ❌ No | Updated title | Only if changing |
| `decision` | string | ❌ No | Updated decision description | Only if changing |
| `factSheets` | array[string] | ❌ No | Updated list of fact sheets | Replaces entire array |
| `status` | enum | ❌ No | Updated status (Proposed/Approved) | Only if changing |
**Output:**
- Returns the fully updated ADL entry object
- `lastEdited` timestamp is automatically updated
- `created` and `id` fields remain unchanged
**Use Cases:**
- Approve a proposed decision (change status)
- Refine decision details
- Add/update related fact sheets
- Correct information
**Important Notes:**
- Only provided fields are updated
- `lastEdited` timestamp is automatically updated
- All other fields remain unchanged
- Error thrown if entry ID not found
---
### 5. adl_delete
**Purpose:** Delete an ADL entry permanently
**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✅ Yes | The unique UUID of the ADL entry to delete |
**Output:**
- **Success:** Confirmation message with deleted entry ID
- **Error:** Error message if entry not found
**Use Cases:**
- Remove obsolete decisions
- Delete duplicate entries
- Clean up proposed decisions that were rejected
**Warning:** This operation is permanent and cannot be undone.
---
### 6. adl_search
**Purpose:** Search for ADL entries using substring matching across multiple fields
**Input:**
| Parameter | Type | Required | Description | Match Type |
|-----------|------|----------|-------------|------------|
| `author` | string | ❌ No | Search term for author field | Case-insensitive substring |
| `title` | string | ❌ No | Search term for title field | Case-insensitive substring |
| `decision` | string | ❌ No | Search term for decision description | Case-insensitive substring |
| `factSheets` | string | ❌ No | Search term for fact sheets | Case-insensitive substring in ANY fact sheet |
| `status` | enum | ❌ No | Filter by status (Proposed/Approved) | Exact match |
**Output:**
```json
[
{
"id": "uuid-v4",
"created": "2026-01-23T10:00:00.000Z",
"lastEdited": "2026-01-23T10:00:00.000Z",
"author": "John Doe",
"title": "Migration to LEANIX",
"decision": "Detailed decision...",
"factSheets": ["LEANIX Platform", "Integration Service"],
"status": "Approved"
}
]
```
**Use Cases:**
- Find all decisions related to specific systems (e.g., "LEA" finds "LEANIX", "Cleaner", "Learning lab")
- Filter decisions by author
- Search for decisions containing specific keywords
- Find all proposed or approved decisions
- Combine multiple search criteria
**Search Behavior:**
- All search criteria use **AND** logic (must match ALL provided criteria)
- Text fields use **case-insensitive substring matching**
- Fact sheets search matches if the search term appears in ANY fact sheet
- Status uses **exact matching**
- Empty/omitted parameters are ignored
- Returns results sorted by creation date (newest first)
**Examples:**
```json
// Find decisions with "LEA" in any fact sheet
{
"name": "adl_search",
"arguments": {
"factSheets": "LEA"
}
}
// Returns entries with "LEANIX", "Cleaner", "Learning lab", etc.
// Find proposed decisions by specific author
{
"name": "adl_search",
"arguments": {
"author": "Jane",
"status": "Proposed"
}
}
// Search for microservices-related decisions
{
"name": "adl_search",
"arguments": {
"decision": "microservice"
}
}
```
---
## Status Values
The `status` field can only have one of two values:
| Status | Description | Use Case |
|--------|-------------|----------|
| `Proposed` | Decision is under consideration | Initial decision documentation, pending review |
| `Approved` | Decision has been approved and adopted | Finalized architectural decisions |
## Error Handling
All MCP tools return errors in the following format:
```json
{
"content": [
{
"type": "text",
"text": "Error: [error message]"
}
],
"isError": true
}
```
Common error scenarios:
- **Entry not found:** When ID doesn't exist (get, update, delete)
- **Invalid input:** When required parameters are missing or invalid
- **Validation errors:** When data doesn't meet schema requirements
## Integration Points
### GraphQL Endpoint
- **URL:** `http://localhost:4000/graphql`
- **Protocol:** HTTP POST
- All MCP tools communicate with the GraphQL backend
### MCP Servers
1. **Stdio Server:** `node mcp-server/server.js`
- For AI assistant integration
- Uses stdin/stdout for communication
2. **HTTP Server:** `http://localhost:5000`
- For web-based integrations
- RESTful-like interface over MCP
## Example Usage
### Creating a Decision
```json
{
"name": "adl_create",
"arguments": {
"author": "Jane Smith",
"title": "Adopt Event-Driven Architecture",
"decision": "We will transition from monolithic to event-driven architecture using Apache Kafka for improved scalability and decoupling of services.",
"factSheets": ["Order Service", "Inventory Service", "Notification Service"],
"status": "Proposed"
}
}
```
### Updating Status to Approved
```json
{
"name": "adl_update",
"arguments": {
"id": "abc123-def456-ghi789",
"status": "Approved"
}
}
```
### Listing All Decisions
```json
{
"name": "adl_list",
"arguments": {}
}
```
### Searching for Decisions
```json
{
"name": "adl_search",
"arguments": {
"factSheets": "LEA"
}
}
```
This will find all decisions containing "LEA" in any fact sheet, including "LEANIX", "Cleaner", "Learning lab", etc.
## Best Practices
1. **Always use descriptive titles:** Make titles clear and searchable
2. **Include context in decisions:** Explain the "why" not just the "what"
3. **Link related fact sheets:** Connect decisions to affected systems/components
4. **Start with Proposed:** Use Proposed status initially, then update to Approved
5. **Keep decisions atomic:** One decision per entry, avoid combining multiple choices
6. **Update lastEdited sparingly:** Only update when making meaningful changes
## Related Documentation
- [GraphQL Examples](GRAPHQL-EXAMPLES.md)
- [MCP Setup Guide](MCP-SETUP.md)
- [API Testing Guide](TESTING.md)
- [Project Architecture](ARCHITECTURE.md)
