135 lines
3.9 KiB
Markdown
135 lines
3.9 KiB
Markdown
# MCP Server Architecture — Research Findings
|
|
|
|
## Official SDK: @modelcontextprotocol/sdk
|
|
|
|
### Basic Server Pattern
|
|
```typescript
|
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
import { z } from "zod";
|
|
|
|
const server = new McpServer({
|
|
name: "my-server",
|
|
version: "1.0.0",
|
|
});
|
|
|
|
// Register a tool
|
|
server.tool(
|
|
"tool-name",
|
|
"Tool description for AI agent",
|
|
{ param: z.string() },
|
|
async ({ param }) => ({
|
|
content: [{ type: "text", text: `Result: ${param}` }],
|
|
}),
|
|
);
|
|
|
|
// Connect via stdio
|
|
const transport = new StdioServerTransport();
|
|
await server.connect(transport);
|
|
```
|
|
|
|
### Transport Options
|
|
1. **stdio** — local process communication (Claude Desktop, Cursor)
|
|
2. **Streamable HTTP** — network transport (replaces deprecated HTTP+SSE)
|
|
- `NodeStreamableHTTPServerTransport` for stateful sessions
|
|
|
|
### Three MCP Primitives
|
|
1. **Tools** — Functions the AI can call (primary focus for ERP integration)
|
|
2. **Resources** — Data the AI can read (documentation, configs, schemas)
|
|
3. **Prompts** — Template conversations for common scenarios
|
|
|
|
## Production MCP Server Requirements
|
|
|
|
### What the spec covers:
|
|
- Capability negotiation (initialize)
|
|
- Tool listing/execution (tools/list, tools/call)
|
|
- Resource listing/reading (resources/list, resources/read)
|
|
- Transport: stdio and Streamable HTTP
|
|
|
|
### What production requires beyond spec:
|
|
- Authentication and authorization (OAuth2, JWT)
|
|
- Rate limiting per IP/token/tool
|
|
- Input schema validation before execution
|
|
- Concurrency control
|
|
- Backpressure when saturated
|
|
- Observability (Prometheus metrics, OpenTelemetry traces)
|
|
- CORS, CSP, max request body size
|
|
- Signal handling (SIGTERM, graceful shutdown)
|
|
- Error handling and retry patterns
|
|
|
|
## Tool Design Best Practices
|
|
|
|
### Schema Precision
|
|
```typescript
|
|
// BAD — vague schema
|
|
inputSchema: { type: "object" }
|
|
|
|
// GOOD — precise and documented
|
|
inputSchema: {
|
|
type: "object",
|
|
properties: {
|
|
query: {
|
|
type: "string",
|
|
description: "SQL SELECT query to execute",
|
|
},
|
|
limit: {
|
|
type: "number",
|
|
minimum: 1,
|
|
maximum: 100,
|
|
default: 10,
|
|
description: "Maximum number of rows to return",
|
|
},
|
|
},
|
|
required: ["query"],
|
|
additionalProperties: false,
|
|
}
|
|
```
|
|
|
|
### Tool Granularity for ERP
|
|
- **Fine-grained** tools: `get_invoice`, `search_customers`, `check_stock`
|
|
- Each tool has **clear purpose** and **precise schema**
|
|
- AI agent uses schema + description to decide when to call
|
|
|
|
### Resource Patterns for Documentation
|
|
```typescript
|
|
server.registerResource(
|
|
{
|
|
uri: "sage://help/invoicing",
|
|
name: "Invoice Help",
|
|
description: "Sage X3 invoicing documentation",
|
|
mimeType: "text/markdown",
|
|
},
|
|
async () => ({
|
|
text: "# Invoice Help\n...",
|
|
}),
|
|
);
|
|
```
|
|
|
|
## Existing ERP MCP Server: @casys/mcp-erpnext
|
|
- Connects AI agents to ERPNext (open-source ERP)
|
|
- Exposes invoices, purchase orders, stock levels, accounting data
|
|
- Good reference for design patterns:
|
|
- Focused scope per tool
|
|
- Strong input validation
|
|
- Read-only defaults with explicit write permissions
|
|
|
|
## Testing
|
|
- **mcp-inspector**: Official CLI testing tool
|
|
- **Programmatic testing**: Use SDK's Client class
|
|
```bash
|
|
npx @modelcontextprotocol/inspector
|
|
```
|
|
|
|
## Key Design Decisions for Sage X3 MCP Server
|
|
1. **Which API(s) to use**: GraphQL (newest, typed) vs REST vs SOAP (legacy but comprehensive)
|
|
2. **Tool granularity**: Domain-specific (get_invoice, search_orders) vs generic (query_graphql)
|
|
3. **Auth strategy**: How to manage Sage X3 credentials (env vars, config file)
|
|
4. **Resource layer**: Sage X3 documentation, schema info as resources
|
|
5. **Prompt templates**: Common troubleshooting scenarios
|
|
|
|
## IMPORTANT NOTE FOR AGENTS
|
|
When using `background_task` or similar functions, **timeouts are in MILLISECONDS not seconds**.
|
|
- 60 seconds = 60000 ms
|
|
- 120 seconds = 120000 ms
|
|
- Default timeout: 120000 ms (2 minutes)
|