chore: add project plan, research, evidence, and workflow artifacts

2026-03-10 17:45:26 +00:00
parent 8fc6d7cbc0
commit 14c2a9f94c
17 changed files with 2015 additions and 0 deletions
--- a/.sisyphus/research/mcp-server-architecture.md
+++ b/.sisyphus/research/mcp-server-architecture.md
@@ -0,0 +1,134 @@
+# 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)