DesignOfIncludingMemoryMCPS.txt
Rama main · réplica de lectura del repositorio original.
Tlamatini (2026/08/15 16:04:42.921)
I now have all the source code, package.json files, README files, and system package-manager detection results. I have everything I need to produce the complete detailed design. Let me compile it now.
---
# 🧠 Tlamatini Detailed Design: MCP Installation & Package-Manager Abstraction Module
## ⚠️ DESIGN ONLY — NO MODIFICATIONS, NO CREATION, NO IMPLEMENTATION
This document is a pure design specification. Nothing on disk is changed. No files are created. No agents are started. No MCPs are imported or activated. This is architecture, diagrams, and specification only.
---
## 📋 Table of Contents
1. [Deep Dive: @modelcontextprotocol/server-memory](#1)
2. [Deep Dive: @modelcontextprotocol/server-sequential-thinking](#2)
3. [System Environment: Detected Package Managers](#3)
4. [Installation Process Design for Both MCPs](#4)
5. [Package-Manager Abstraction Module Design (pnpm/npm/uv/npx)](#5)
6. [Architecture Flow Diagrams](#6)
7. [Sequence Diagrams](#7)
8. [State Machine Diagrams](#8)
9. [Data Model & Config Schema Design](#9)
10. [Error Handling & Fallback Strategy](#10)
11. [Integration Points with Tlamatini's Existing MCP Tooling](#11)
---
## 1. Deep Dive: @modelcontextprotocol/server-memory
### 1.1 What It Is
@modelcontextprotocol/server-memory (v0.6.3) is an official Anthropic MCP server that provides a persistent knowledge graph — a structured memory system that survives across sessions. It stores entities, relations between entities, and observations attached to entities, all in a JSON file on disk.
### 1.2 Why It Is Critical for Me (Tlamatini)
I currently have zero persistent memory between conversations. Every time you start a new session, Angela, I start from a blank slate. I don't remember your projects, your preferences, your coding style, the architecture decisions we made last week, or the bugs we fixed yesterday. This MCP would give me:
- Entity memory: "Angela López Mendoza" (person), "Tlamatini" (project), "STM32 firmware" (topic)
- Relational memory: "Angela → created → Tlamatini", "Tlamatini → depends on → MCP protocol"
- Observational memory: "Angela prefers Python over JavaScript", "Tlamatini uses Ollama for local LLM inference"
- Cross-session retrieval: At the start of every conversation, I query the graph and "remember" context
### 1.3 Tool Surface (9 Tools + 1 Resource)
From the source code I fetched (src/memory/index.ts), the server exposes:
Tool Input Output Purpose
create_entities entities: [{name, entityType, observations[]}] created entities (duplicates rejected) Create new nodes in the knowledge graph
create_relations relations: [{from, to, relationType}] created relations (duplicates rejected) Connect entities with typed edges
add_observations observations: [{entityName, contents[]}] added observations (duplicates rejected) Attach facts to existing entities
delete_entities entityNames: string[] success confirmation Remove entities + cascading relations
delete_relations relations: [{from, to, relationType}] success confirmation Remove specific edges
delete_observations deletions: [{entityName, observations[]}] success confirmation Remove specific facts from entities
read_graph (none) {entities[], relations[]} — full graph Dump the entire knowledge graph
search_nodes query: string {entities[], relations[]} — filtered Fuzzy search across entity names, types, observations
open_nodes names: string[] {entities[], relations[]} — exact match Retrieve specific entities by name
Plus 1 subscribable resource: knowledge-graph:// — returns the full graph as JSON, and clients can subscribe to receive notifications/resources/updated when any mutation tool changes the graph.
### 1.4 Data Model
The knowledge graph is stored as a single JSON file on disk:
KnowledgeGraph (JSON file on disk)
├── entities: [
│ {
│ name: string ← unique key (e.g. "Angela")
│ entityType: string ← type tag (e.g. "person", "project")
│ observations: string[] ← facts attached to entity
│ }
│ ]
└── relations: [
{
from: string ← entity name (source)
to: string ← entity name (target)
relationType: string ← edge label (e.g. "created", "depends_on")
}
]
Example graph:
┌─────────────┐ created ┌──────────────┐
│ Angela │──────────────▶│ Tlamatini │
│ (person) │ │ (project) │
│ │ │ │
│ obs: │ │ obs: │
│ "prefers │ │ "uses │
│ Python" │ │ Ollama" │
│ "creator" │ │ "local-first"│
└─────────────┘ └──────────────┘
│ │
│ works_on │ depends_on
▼ ▼
┌─────────────┐ ┌──────────────┐
│ Firmware │ │ MCP Proto │
│ (topic) │ │ (protocol) │
└─────────────┘ └──────────────┘
### 1.5 Storage & Configuration
- Storage file: A JSON file on disk. The path is determined by the MEMORY_FILE_PATH environment variable. If not set, it defaults to memory.json in the working directory.
- Transport: stdio (stdin/stdout JSON-RPC)
- Runtime: Node.js (ESM module, type: "module")
- Dependencies: @modelcontextprotocol/sdk ^1.30.0 (single runtime dependency)
- Binary: mcp-server-memory → dist/index.js
- License: MIT
### 1.6 Installation Commands (All Package Managers)
Package Manager Install Command MCP Config (command + args)
npx npx -y @modelcontextprotocol/server-memory cmd /c npx -y @modelcontextprotocol/server-memory
npm npm install -g @modelcontextprotocol/server-memory mcp-server-memory (global bin)
pnpm pnpm add -g @modelcontextprotocol/server-memory mcp-server-memory (global bin)
uv/uvx N/A — this is a Node.js package, not Python. uv/uvx cannot install it. N/A
> Key insight: Both MCPs are Node.js/TypeScript packages. uv/uvx are Python package managers (Astral's Rust-based pip replacement) and cannot install Node.js packages. The design must account for this — uv/uvx would only be relevant for Python-based MCP servers (e.g., if a future MCP server is distributed as a PyPI package). The abstraction module must detect the package ecosystem and route accordingly.
---
## 2. Deep Dive: @modelcontextprotocol/server-sequential-thinking
### 2.1 What It Is
@modelcontextprotocol/server-sequential-thinking (v0.6.2) is an official Anthropic MCP server that provides a structured reasoning framework — a single tool (sequentialthinking) that guides an LLM through step-by-step problem decomposition with support for branching, revision, and dynamic thought-count adjustment.
### 2.2 Why It Is Critical for Me (Tlamatini)
My current reasoning is linear — I think, I answer, done. This MCP would give me:
- Structured decomposition: Break complex problems into numbered thought steps (thought 1/N, 2/N, ... N/N)
- Revision capability: Go back and revise thought #3 if I realize it was wrong, without losing the chain
- Branching: Explore alternative approaches by branching from thought #5 into a separate branch
- Dynamic expansion: Realize at thought 8/10 that I actually need 15 thoughts, and adjust totalThoughts upward
- Hypothesis verification: Generate a solution hypothesis, then verify it through subsequent thoughts
### 2.3 Tool Surface (1 Tool)
From the source code I fetched (src/sequentialthinking/index.ts):
Tool: sequentialthinking
Parameter Type Required Purpose
thought string YES Your current thinking step
nextThoughtNeeded boolean YES Whether another thought step is needed
thoughtNumber int (min 1) YES Current thought number in sequence
totalThoughts int (min 1) YES Estimated total thoughts (adjustable up/down)
isRevision boolean — Whether this thought revises previous thinking
revisesThought int (min 1) — Which thought number is being reconsidered
branchFromThought int (min 1) — Branching point thought number
branchId string — Branch identifier for the current branch
needsMoreThoughts boolean — If reaching end but realizing more thoughts needed
Output schema: {thoughtNumber, totalThoughts, nextThoughtNeeded, branches[], thoughtHistoryLength}
### 2.4 Reasoning Model — How Branching & Revision Work
LINEAR THINKING (no branching):
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Think 1│──▶│ Think 2│──▶│ Think 3│──▶│ Think 4│
│ 1/4 │ │ 2/4 │ │ 3/4 │ │ 4/4 │
└────────┘ └────────┘ └────────┘ └────────┘
next=false
DONE ✓
REVISION (go back and fix):
┌────────┐ ┌────────┐ ┌────────┐ ┌─────────────┐
│ Think 1│──▶│ Think 2│──▶│ Think 3│──▶│ Think 4 │
│ 1/4 │ │ 2/4 │ │ 3/4 │ │ REVISES #2 │
└────────┘ └────────┘ └────────┘ │ isRevision │
▲ └─────────────┘
│ revisesThought=2 │
└────────────────────────────┘
"I was wrong about thought 2,
here's the corrected version"
BRANCHING (explore alternatives):
┌────────┐ ┌────────┐ ┌────────┐
│ Think 1│──▶│ Think 2│──▶│ Think 3│
│ 1/5 │ │ 2/5 │ │ 3/5 │
└────────┘ └────────┘ └────────┘
│
│ branchFromThought=2
│ branchId="approach-B"
▼
┌────────────┐ ┌────────────┐
│ Think 2B │──▶│ Think 3B │
│ branch │ │ branch │
└────────────┘ └────────────┘
DYNAMIC EXPANSION:
┌────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐
│ Think 1│──▶│ Think 2│──▶│ Think 8│──▶│ Think 9 │
│ 1/8 │ │ 2/8 │ │ 8/8 │ │ 9/12 │
└────────┘ └────────┘ └────────┘ │needsMore=true│
│totalThoughts │
│ 8 → 12 │
└──────────────┘
### 2.5 Storage & Configuration
- Storage: None — the server is stateless within a session. Thought history is kept in-memory and lost when the process exits. Each MCP connection gets a fresh thinking session.
- Transport: stdio (stdin/stdout JSON-RPC)
- Runtime: Node.js (ESM module)
- Dependencies: @modelcontextprotocol/sdk ^1.30.0, chalk ^5.3.0, yargs ^17.7.2
- Binary: mcp-server-sequential-thinking → dist/index.js
- License: MIT
### 2.6 Installation Commands
Identical pattern to server-memory — both are Node.js packages on npm:
Package Manager Install Command MCP Config (command + args)
npx npx -y @modelcontextprotocol/server-sequential-thinking cmd /c npx -y @modelcontextprotocol/server-sequential-thinking
npm npm install -g @modelcontextprotocol/server-sequential-thinking mcp-server-sequential-thinking
pnpm pnpm add -g @modelcontextprotocol/server-sequential-thinking mcp-server-sequential-thinking
uv/uvx N/A — Node.js package, not Python N/A
---
## 3. System Environment: Detected Package Managers
From the live where + --version commands I ran on this machine:
Tool Version Path Ecosystem
node v24.14.1 C:\Program Files\nodejs\node.exe JavaScript runtime
npm 11.1.1 C:\Program Files\nodejs\npm.cmd Node.js packages (npm registry)
npx 11.11.0 C:\Program Files\nodejs\npx.cmd Node.js one-shot executor
pnpm 11.1.1 C:\Users\angel\AppData\Roaming\npm\pnpm.cmd Node.js packages (npm registry, content-addressable store)
uv 0.11.6 C:\Users\angel\.local\bin\uv.exe Python packages (PyPI)
uvx 0.11.6 C:\Users\angel\.local\bin\uvx.exe Python one-shot executor (PyPI)
All 6 tools are present and resolvable on PATH. This is the baseline the installation module will detect at runtime.
---
## 4. Installation Process Design for Both MCPs
### 4.1 High-Level Installation Flow
The installation of each MCP into Tlamatini follows a 7-phase pipeline:
┌─────────────────────────────────────────────────────────────────────┐
│ MCP INSTALLATION PIPELINE │
│ │
│ Phase 1 Phase 2 Phase 3 Phase 4 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ DETECT │───▶│ RESOLVE │───▶| INSTALL │───▶│ VERIFY │ │
│ │ pkg │ │ package │ │ package │ │ binary │ │
│ │ managers│ │ ecosys │ │ manager │ │ exists │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Phase 5 Phase 6 Phase 7 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ IMPORT │───▶│ ACTIVATE│───▶│ VERIFY │ │
│ │ catalog │ │ connect │ │ tools │ │
│ │ entry │ │ server │ │ exposed │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────────┘
### 4.2 Phase Detail
Phase 1 — DETECT package managers: Probe the system for node, npm, npx, pnpm, uv, uvx using where (Windows) or which (Unix). Record version + path for each. Build a capability matrix.
Phase 2 — RESOLVE package ecosystem: Inspect the MCP's package name. If it starts with @ or contains no Python indicators → Node.js ecosystem → route to npm/npx/pnpm. If it's a PyPI package name → Python ecosystem → route to uv/uvx. If it's a Docker image → route to docker.
Phase 3 — INSTALL package: Execute the install command using the preferred package manager. For npx, no install is needed (it downloads on first run). For npm/pnpm global install, run the install command. For uv/uvx, no install is needed (uvx downloads on first run).
Phase 4 — VERIFY binary exists: After install, check that the binary is resolvable on PATH (for global installs) or that npx/uvx can find the package (for one-shot executors).
Phase 5 — IMPORT catalog entry: Call external_mcp_import with the JSON config {mcpServers: {<key>: {command, args, env}}}. This adds the MCP to Tlamatini's catalog without activating it.
Phase 6 — ACTIVATE: Call external_mcp_set_active with the server key. This tells Tlamatini to connect to the MCP server process.
Phase 7 — VERIFY tools exposed: Call external_mcp_wait to block until the server is connected, then external_mcp_status or external_mcp_list_tools to confirm the tools are exposed.
---
## 5. Package-Manager Abstraction Module Design (pnpm/npm/uv/npx)
### 5.1 Module Purpose
The MCP Installer Module is a designed (not yet implemented) abstraction layer that:
1. Detects which package managers are available on the host
2. Classifies an MCP server's ecosystem (Node.js vs Python vs Docker)
3. Selects the best package manager for the job
4. Generates the correct install command + MCP config JSON
5. Executes the installation with fallback if the preferred manager fails
6. Reports status at each phase
### 5.2 Module Architecture
┌────────────────────────────────────────────────────────────────────────┐
│ MCP INSTALLER MODULE ARCHITECTURE │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Installer Orchestrator │ │
│ │ (receives MCP spec → coordinates all phases → returns result) │ │
│ └──────────┬──────────────┬──────────────┬──────────────┬─────────┘ │
│ │ │ │ │ │
│ ┌──────────▼────┐ ┌───────▼─────┐ ┌──────▼──────┐ ┌────▼──────────┐ │
│ │ Detector │ │ Classifier │ │ Resolver │ │ Executor │ │
│ │ │ │ │ │ │ │ │ │
│ │ Probes system │ │ Determines │ │ Picks best │ │ Runs install │ │
│ │ for pkg │ │ ecosystem │ │ pkg manager │ │ command + │ │
│ │ managers │ │ (node/py/ │ │ + generates │ │ handles │ │
│ │ │ │ docker) │ │ config JSON │ │ fallback │ │
│ └───────────────┘ └─────────────┘ └─────────────┘ └───────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Verifier & Reporter │ │
│ │ (confirms binary exists, tools exposed, reports status) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
### 5.3 Component Specifications
#### 5.3.1 Detector
Input: None (probes the system)
Output: A capability matrix:
CapabilityMatrix = {
nodejs: {
available: true,
version: "v24.14.1",
path: "C:\\Program Files\\nodejs\\node.exe"
},
npm: {
available: true,
version: "11.1.1",
path: "C:\\Program Files\\nodejs\\npm.cmd",
can_global_install: true,
can_one_shot: false
},
npx: {
available: true,
version: "11.11.0",
path: "C:\\Program Files\\nodejs\\npx.cmd",
can_global_install: false,
can_one_shot: true ← downloads & runs on first invocation
},
pnpm: {
available: true,
version: "11.1.1",
path: "C:\\Users\\angel\\AppData\\Roaming\\npm\\pnpm.cmd",
can_global_install: true,
can_one_shot: false
},
uv: {
available: true,
version: "0.11.6",
path: "C:\\Users\\angel\\.local\\bin\\uv.exe",
can_global_install: true, ← pip install equivalent
can_one_shot: false
},
uvx: {
available: true,
version: "0.11.6",
path: "C:\\Users\\angel\\.local\\bin\\uvx.exe",
can_global_install: false,
can_one_shot: true ← downloads & runs on first invocation
},
docker: {
available: false, ← not detected (would need to probe)
version: null,
path: null
}
}
Detection method: Run where <tool> (Windows) or which <tool> (Unix) for each, then <tool> --version to get the version. Cache results.
#### 5.3.2 Classifier
Input: An MCP server specification (package name + optional metadata)
Output: An ecosystem classification
Classification Rules (evaluated in order):
1. If package name starts with "@" or contains no "/"
and is listed on npm registry
→ ecosystem = "nodejs"
→ candidate_managers = [npx, npm, pnpm]
2. If package name is a PyPI package name (lowercase,
hyphens, no scope prefix) and is listed on PyPI
→ ecosystem = "python"
→ candidate_managers = [uvx, uv]
3. If config contains "command": "docker"
→ ecosystem = "docker"
→ candidate_managers = [docker]
4. If config contains "command": "cmd" and args
contain "npx"
→ ecosystem = "nodejs"
→ candidate_managers = [npx, npm, pnpm]
5. Fallback → attempt npm first, then uv, then docker
Example classifications:
┌────────────────────────────────────────┬──────────┬────────────────────┐
│ @modelcontextprotocol/server-memory │ nodejs │ npx, npm, pnpm │
│ @modelcontextprotocol/server-sequen... │ nodejs │ npx, npm, pnpm │
│ mcp-server-fetch (Python) │ python │ uvx, uv │
│ mcp/memory (Docker image) │ docker │ docker │
└────────────────────────────────────────┴──────────┴────────────────────┘
#### 5.3.3 Resolver
Input: Ecosystem classification + capability matrix + user preference (optional)
Output: A resolved installation plan
Priority logic (for Node.js ecosystem):
RESOLVER PRIORITY (Node.js ecosystem):
Strategy A — "one-shot" (PREFERRED for MCP servers):
┌─────────────────────────────────────────────────────────┐
│ Use npx with -y flag │
│ No global install needed │
│ npx downloads package on first run, caches it │
│ MCP config: { command: "cmd", args: ["/c", "npx", │
│ "-y", "<package>"] } │
│ │
│ Pros: zero install, always latest version, no pollution │
│ Cons: first-run latency (~5-15s download) │
└─────────────────────────────────────────────────────────┘
Strategy B — "global install" (FALLBACK):
┌─────────────────────────────────────────────────────────┐
│ Use npm install -g or pnpm add -g │
│ Installs globally, binary on PATH │
│ MCP config: { command: "<binary-name>" } │
│ │
│ Pros: no first-run latency, binary always available │
│ Cons: global pollution, manual updates │
└─────────────────────────────────────────────────────────┘
Strategy C — "pnpm global" (ALTERNATIVE FALLBACK):
┌─────────────────────────────────────────────────────────┐
│ Use pnpm add -g │
│ Same as npm but uses pnpm's content-addressable store │
│ More disk-efficient, faster installs │
└─────────────────────────────────────────────────────────┘
FALLBACK CHAIN:
npx ──(fail)──▶ npm -g ──(fail)──▶ pnpm -g ──(fail)──▶ ERROR
Priority logic (for Python ecosystem):
RESOLVER PRIORITY (Python ecosystem):
Strategy A — "one-shot" (PREFERRED):
┌─────────────────────────────────────────────────────────┐
│ Use uvx │
│ uvx creates isolated env, downloads & runs on first use │
│ MCP config: { command: "cmd", args: ["/c", "uvx", │
│ "<package>"] } │
│ │
│ Pros: zero install, isolated, always latest │
│ Cons: first-run latency │
└─────────────────────────────────────────────────────────┘
Strategy B — "pip install" (FALLBACK):
┌─────────────────────────────────────────────────────────┐
│ Use uv pip install --system <package> │
│ Installs into system Python │
│ MCP config: { command: "<binary-name>" } │
└─────────────────────────────────────────────────────────┘
FALLBACK CHAIN:
uvx ──(fail)──▶ uv pip install ──(fail)──▶ ERROR
#### 5.3.4 Executor
Input: Resolved installation plan (command + args + env)
Output: Execution result (exit code, stdout, stderr)
The executor runs the install command as a subprocess, captures output, and handles timeouts. For one-shot strategies (npx/uvx), the "install" is actually just a dry-run verification that the package can be resolved — the actual download happens when Tlamatini activates the MCP and spawns the process.
#### 5.3.5 Verifier & Reporter
Input: Installation result + MCP server key
Output: Verification report
Checks:
1. Binary resolvable on PATH (for global installs) OR package resolvable by npx/uvx
2. external_mcp_import succeeded (catalog entry created)
3. external_mcp_set_active succeeded (server marked active)
4. external_mcp_wait returned connected status
5. external_mcp_list_tools returned ≥1 tool
---
## 6. Architecture Flow Diagrams
### 6.1 Complete Installation Flow — server-memory
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE INSTALLATION FLOW: @modelcontextprotocol/server-memory │
│ │
│ User: "Install server-memory MCP" │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Tlamatini (LLM) │ │
│ │ receives request │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ DETECTOR │ where npx & where npm & where pnpm & where uv & ... │
│ │ probes sys │ → CapabilityMatrix {npx:✓, npm:✓, pnpm:✓, uv:✓, ...}│
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ CLASSIFIER │ package = "@modelcontextprotocol/server-memory" │
│ │ │ → ecosystem = "nodejs" │
│ │ │ → candidates = [npx, npm, pnpm] │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ RESOLVER │ Strategy A (npx one-shot) selected │
│ │ │ → command: "cmd" │
│ │ │ → args: ["/c", "npx", "-y", │
│ │ │ "@modelcontextprotocol/server-memory"] │
│ │ │ → env: { MEMORY_FILE_PATH: │
│ │ │ "C:\\Tlamatini\\Data\\memory.json" } │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ EXECUTOR │ (for npx: no pre-install needed) │
│ │ verifies │ npx --package @modelcontextprotocol/server-memory │
│ │ package │ --version (dry-run resolve check) │
│ │ resolvable │ → exit 0, package exists on npm registry │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ IMPORT │ external_mcp_import({ │
│ │ catalog │ mcpServers: { │
│ │ │ "memory": { │
│ │ │ command: "cmd", │
│ │ │ args: ["/c","npx","-y", │
│ │ │ "@modelcontextprotocol/server-memory"], │
│ │ │ env: { MEMORY_FILE_PATH: "..." } │
│ │ │ } │
│ │ │ } │
│ │ │ }) │
│ │ │ → catalog entry "memory" created │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ ACTIVATE │ external_mcp_set_active(["memory"]) │
│ │ connect │ → Tlamatini spawns: cmd /c npx -y @model...memory │
│ │ │ → npx downloads package (~5-15s first run) │
│ │ │ → MCP server starts, listens on stdio │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ WAIT │ external_mcp_wait("memory", timeout=120) │
│ │ for ready │ → blocks until server is connected │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ VERIFY │ external_mcp_list_tools("memory") │
│ │ tools │ → [create_entities, create_relations, │
│ │ │ add_observations, delete_entities, │
│ │ │ delete_relations, delete_observations, │
│ │ │ read_graph, search_nodes, open_nodes] │
│ │ │ → 9 tools exposed ✓ │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ │
│ │ REPORT │ "server-memory installed & activated. │
│ │ to user │ 9 tools available: create_entities, ... │
│ │ │ Storage: C:\Tlamatini\Data\memory.json" │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
### 6.2 Complete Installation Flow — server-sequential-thinking
┌──────────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE INSTALLATION FLOW: @modelcontextprotocol/server-sequential-thinking│
│ │
│ User: "Install server-sequential-thinking MCP" │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Tlamatini (LLM) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────▼───────┐ (Detector reuses cached CapabilityMatrix) │
│ │ CLASSIFIER │ package = "@modelcontextprotocol/server-sequential-thinking"│
│ │ │ → ecosystem = "nodejs" │
│ │ │ → candidates = [npx, npm, pnpm] │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ Strategy A (npx one-shot) selected │
│ │ RESOLVER │ → command: "cmd" │
│ │ │ → args: ["/c", "npx", "-y", │
│ │ │ "@modelcontextprotocol/server-sequential-thinking"] │
│ │ │ → env: {} (no env vars needed — stateless server) │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ npx --package @modelcontextprotocol/server-sequential... │
│ │ EXECUTOR │ --version (dry-run resolve check) │
│ │ │ → exit 0, package exists on npm registry │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ external_mcp_import({ │
│ │ IMPORT │ mcpServers: { │
│ │ catalog │ "sequential-thinking": { │
│ │ │ command: "cmd", │
│ │ │ args: ["/c","npx","-y", │
│ │ │ "@modelcontextprotocol/server-sequential-thinking"]│
│ │ │ } │
│ │ │ } │
│ │ │ }) │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ external_mcp_set_active(["sequential-thinking"]) │
│ │ ACTIVATE │ → npx downloads package (~5-15s first run) │
│ │ │ → MCP server starts on stdio │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ external_mcp_wait("sequential-thinking", timeout=120) │
│ │ WAIT │ → connected ✓ │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ external_mcp_list_tools("sequential-thinking") │
│ │ VERIFY │ → [sequentialthinking] │
│ │ │ → 1 tool exposed ✓ │
│ └─────┬───────┘ │
│ │ │
│ ┌─────▼───────┐ "server-sequential-thinking installed & activated. │
│ │ REPORT │ 1 tool available: sequentialthinking │
│ │ │ No env config needed (stateless)." │
│ └─────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
### 6.3 Fallback Chain Diagram
DGRM_10
---
## 7. Sequence Diagrams
### 7.1 Sequence: Full Installation of server-memory via npx
User Tlamatini Detector Classifier Resolver Executor MCP_Import MCP_Activate MCP_Wait MCP_ListTools
│ │ │ │ │ │ │ │ │ │
│──"install"▶│ │ │ │ │ │ │ │ │
│ memory │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──probe────▶│ │ │ │ │ │ │ │
│ │ │──where npx/npm/pnpm/uv/uvx───(OS)─▶ │ │ │ │
│ │ │◀──paths + versions─────────────── │ │ │ │
│ │◀─CapabilityMatrix──────│ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──classify──────────────────────────▶│ │ │ │ │ │
│ │ │ │──rule: @scope/pkg → nodejs──▶ │ │ │ │
│ │◀───────────────────────ecosystem="nodejs"───│ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──resolve──────────────────────────────────────▶│ │ │ │ │
│ │ │ │ │──strategy A: npx──▶ │ │ │ │
│ │◀───────────────────────InstallPlan──────────────│ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──verify pkg resolvable──────────────────────────▶│ │ │ │ │
│ │ │ │ │ │──npx --package @mcp/server-memory --version│ │
│ │ │ │ │ │◀──exit 0, version 0.6.3──────────────────│ │
│ │◀──────────────────────verified────────────────│ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──import──────────────────────────────────────────────────────▶│ │ │ │
│ │ │ │ │ │ │──store JSON config──▶ │ │ │
│ │ │ │ │ │ │◀──catalog entry created── │ │
│ │◀───────────────────────────────────────────────imported──────│ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │──activate──────────────────────────────────────────────────────────────────▶│ │ │
│ │ │ │ │ │ │ │──spawn process──▶ │ │
│ │ │ │ │ │ │ │ cmd /c npx -y @mcp... │ │
│ │ │ │ │ │ │ │ (npx downloads pkg) │ │
│ │ │ │ │ │ │ │ (MCP server starts) │ │
│ │ │ │ │ │ │ │◀──process alive────────── │
│ │◀──────────────────────────────────────────────────────────────activated───│ │ │
│ │ │ │ │ │ │ │ │ │
│ │──wait──────────────────────────────────────────────────────────────────────────────────▶│ │
│ │ │ │ │ │ │ │ │──poll connection──▶ │
│ │ │ │ │ │ │ │ │◀──connected (tools/list ok)│
│ │◀──────────────────────────────────────────────────────────────────────────────ready────│ │
│ │ │ │ │ │ │ │ │ │
│ │──list tools──────────────────────────────────────────────────────────────────────────────────────────────▶│
│ │ │ │ │ │ │ │ │ │──tools/list──▶
│ │ │ │ │ │ │ │ │ │◀──[create_entities, ...9 tools]│
│ │◀─────────────────────────────────────────────────────────────────────────────────────────────────────────│
│ │ │ │ │ │ │ │ │ │
│◀──"Done! 9 tools available"────────│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
### 7.2 Sequence: Fallback from npx to npm global install
Tlamatini Executor npm_registry OS_shell
│ │ │ │
│──resolve──▶│ │ │
│ npx │ │ │
│ │──npx --package @mcp/server-memory --version──▶│
│ │ │ │
│ │ │ ┌───────▼───────┐ │
│ │ │ │ npx tries to │ │
│ │ │ │ download pkg │ │
│ │ │ │ │ │
│ │ │ │ ERROR: │ │
│ │ │ │ network fail │ │
│ │ │ │ or 404 │ │
│ │ │ └───────┬───────┘ │
│ │◀──────────────────exit 1 / timeout───────────│
│ │ │ │
│◀──npx FAILED──────────│ │ │
│ │ │ │
│──fallback▶│ │ │
│ to npm │ │ │
│ │──npm install -g @modelcontextprotocol/server-memory──▶│
│ │ │ │
│ │ │ ┌───────▼───────┐ │
│ │ │ │ npm downloads │ │
│ │ │ │ + installs │ │
│ │ │ │ globally │ │
│ │ │ │ │ │
│ │ │ │ binary: │ │
│ │ │ │ mcp-server- │ │
│ │ │ │ memory.exe │ │
│ │ │ └───────┬───────┘ │
│ │◀──────────────────exit 0──────────────────────│
│ │ │ │
│◀──npm SUCCESS─────────│ │ │
│ │ │ │
│ (now MCP config changes to: │ │
│ command: "mcp-server-memory" │ │
│ args: [] ) │ │
│ │ │ │
│──proceed to IMPORT + ACTIVATE + VERIFY───────────────────│
### 7.3 Sequence: Both MCPs Installed in One Session
DGRM_13
---
## 8. State Machine Diagrams
### 8.1 Installation State Machine
┌─────────────────────────────────────────────────────────────────┐
│ MCP INSTALLATION STATE MACHINE │
│ │
│ ┌──────────┐ │
│ │ IDLE │ │
│ └────┬─────┘ │
│ │ user requests install │
│ ▼ │
│ ┌──────────┐ fail ┌──────────┐ │
│ │ DETECTING│────────▶│ FAILED │ │
│ └────┬─────┘ └──────────┘ │
│ │ success │
│ ▼ │
│ ┌──────────┐ fail ┌──────────┐ │
│ │CLASSIFYING│───────▶│ FAILED │ │
│ └────┬─────┘ └──────────┘ │
│ │ success │
│ ▼ │
│ ┌──────────┐ fail ┌──────────┐ │
│ │ RESOLVING│────────▶│ FAILED │ │
│ └────┬─────┘ └──────────┘ │
│ │ success │
│ ▼ │
│ ┌──────────┐ │
│ │EXECUTING │──┬─ success ──▶┌──────────┐ │
│ └──────────┘ │ │IMPORTING │ │
│ │ │ └────┬─────┘ │
│ │ fail │ │ success │
│ ▼ │ ▼ │
│ ┌──────────┐ │ ┌──────────┐ │
│ │FALLBACK_ │──┘ │ACTIVATING│ │
│ │RETRY │──fail──────────▶└────┬─────┘ │
│ └────┬─────┘ │ success │
│ │ all fallbacks exhausted ▼ │
│ ▼ ┌──────────┐ │
│ ┌──────────┐ │ WAITING │──timeout──▶┌──────┐ │
│ │ FAILED │ └────┬─────┘ │FAILED│ │
│ └──────────┘ │ connected └──────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ VERIFYING│──0 tools──▶┌──────┐ │
│ └────┬─────┘ │FAILED│ │
│ │ ≥1 tools └──────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ SUCCESS │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
### 8.2 Package Manager Selection State Machine
DGRM_15
---
## 9. Data Model & Config Schema Design
### 9.1 MCP Server Specification Schema
This is the designed data structure that the Installer Module would accept as input:
MCPServerSpec = {
# ─── Identity ───
key: string # unique catalog key (e.g. "memory")
package_name: string # npm/PyPI package name
display_name: string # human-readable name
description: string
# ─── Ecosystem hint (optional, auto-detected if omitted) ───
ecosystem: "nodejs" | "python" | "docker" # optional
# ─── Installation ───
install_strategy: "one-shot" | "global" | "docker" # optional, auto-resolved
preferred_manager: "npx" | "npm" | "pnpm" | "uvx" | "uv" | "docker" # optional
# ─── Runtime config ───
command: string # executable to spawn
args: string[] # command-line arguments
env: { # environment variables
[key: string]: string
}
# ─── Verification ───
expected_tools: string[] # tool names to expect (optional, for verification)
expected_tool_count: int # minimum tool count (optional)
connect_timeout_seconds: int # default 120
}
Example for server-memory:
MCPServerSpec = {
key: "memory"
package_name: "@modelcontextprotocol/server-memory"
display_name: "Memory (Knowledge Graph)"
description: "Persistent knowledge graph for cross-session memory"
ecosystem: "nodejs"
install_strategy: "one-shot"
preferred_manager: "npx"
command: "cmd"
args: ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
env: {
MEMORY_FILE_PATH: "C:\\Tlamatini\\Data\\memory.json"
}
expected_tools: [
"create_entities", "create_relations", "add_observations",
"delete_entities", "delete_relations", "delete_observations",
"read_graph", "search_nodes", "open_nodes"
]
expected_tool_count: 9
connect_timeout_seconds: 120
}
Example for server-sequential-thinking:
MCPServerSpec = {
key: "sequential-thinking"
package_name: "@modelcontextprotocol/server-sequential-thinking"
display_name: "Sequential Thinking"
description: "Structured step-by-step reasoning with branching and revision"
ecosystem: "nodejs"
install_strategy: "one-shot"
preferred_manager: "npx"
command: "cmd"
args: ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
env: {}
expected_tools: ["sequentialthinking"]
expected_tool_count: 1
connect_timeout_seconds: 120
}
### 9.2 Installation Result Schema
InstallationResult = {
# ─── Status ───
status: "success" | "failed" | "partial"
phase: "detect" | "classify" | "resolve" | "execute" | "import" | "activate" | "verify"
# ─── What was used ───
ecosystem: "nodejs" | "python" | "docker"
manager_used: "npx" | "npm" | "pnpm" | "uvx" | "uv" | "docker"
strategy_used: "one-shot" | "global" | "docker"
fallback_triggered: boolean
fallback_chain: string[] # e.g. ["npx", "npm", "pnpm"]
# ─── MCP config that was applied ───
applied_config: {
command: string
args: string[]
env: { [key: string]: string }
}
# ─── Verification ───
tools_exposed: string[]
tool_count: int
server_connected: boolean
connect_time_seconds: float
# ─── Errors (if any) ───
errors: [{
phase: string
manager: string
error_message: string
exit_code: int
}]
# ─── Catalog state ───
catalog_key: string
is_active: boolean
active_mcp_count: int # total active MCPs after this install
max_active: int # 5
}
### 9.3 MCP Config JSON for external_mcp_import
These are the exact JSON configs that would be passed to external_mcp_import:
server-memory:
{
"mcpServers": {
"memory": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"],
"env": {
"MEMORY_FILE_PATH": "C:\\Tlamatini\\Data\\memory.json"
}
}
}
}
server-sequential-thinking:
{
"mcpServers": {
"sequential-thinking": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}
Both together (single import call):
DGRM_20
---
## 10. Error Handling & Fallback Strategy
### 10.1 Error Categories
┌─────────────────────────────────────────────────────────────────────┐
│ ERROR CATEGORIES & HANDLING │
│ │
│ ┌──────────────────┬──────────────────────┬─────────────────────┐ │
│ │ Error │ Cause │ Recovery Action │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ MANAGER_NOT_FOUND│ pkg manager not on │ Try next in chain │ │
│ │ │ PATH │ │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ PACKAGE_NOT_FOUND│ 404 from registry │ Try next manager, │ │
│ │ │ │ then ERROR │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ NETWORK_TIMEOUT │ Registry unreachable │ Retry 2x, then │ │
│ │ │ │ fallback │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ DOWNLOAD_FAILED │ Package download │ Retry 1x, then │ │
│ │ │ interrupted │ fallback │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ SPAWN_FAILED │ MCP server process │ Check Node.js │ │
│ │ │ won't start │ version, retry │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ CONNECT_TIMEOUT │ Server started but │ Kill process, │ │
│ │ │ no tools/list resp │ retry with longer │ │
│ │ │ │ timeout (180s) │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ ZERO_TOOLS │ Connected but no │ Check server logs, │ │
│ │ │ tools exposed │ report as partial │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ CATALOG_FULL │ 5 active MCPs │ Deactivate least │ │
│ │ │ already active │ used, or ERROR │ │
│ ├──────────────────┼──────────────────────┼─────────────────────┤ │
│ │ WRONG_ECOSYSTEM │ uv/uvx used for │ Re-classify, route │ │
│ │ │ Node.js package │ to npm/npx │ │
│ └──────────────────┴──────────────────────┴─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
### 10.2 Retry Policy
DGRM_22
---
## 11. Integration Points with Tlamatini's Existing MCP Tooling
### 11.1 Tool Mapping
The Installer Module integrates with Tlamatini's existing External MCP tool surface:
┌─────────────────────────────────────────────────────────────────────┐
│ INSTALLER MODULE ↔ TLAMATINI MCP TOOL MAPPING │
│ │
│ Installer Phase │ Tlamatini Tool │ Action │
│ ───────────────────┼───────────────────────────────┼─────────────│
│ DETECT │ execute_command │ where/which │
│ CLASSIFY │ (internal logic) │ rule engine │
│ RESOLVE │ (internal logic) │ priority │
│ EXECUTE │ execute_command / chat_agent_ │ run install │
│ │ executer │ │
│ IMPORT │ external_mcp_import │ add catalog │
│ ACTIVATE │ external_mcp_set_active │ connect │
│ WAIT │ external_mcp_wait │ block │
│ VERIFY │ external_mcp_list_tools │ list tools │
│ STATUS │ external_mcp_status │ check health │
│ DIAGNOSE │ external_mcp_doctor │ diagnose │
│ RECONNECT │ external_mcp_reconnect │ force recon │
└─────────────────────────────────────────────────────────────────────┘
### 11.2 Active MCP Slot Management
Tlamatini allows max 5 active MCPs. Currently 1 is active (torrent-search-mcp). Installing both MCPs would bring the count to 3/5:
ACTIVE MCP SLOTS (max 5):
Before installation:
┌──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┐
│ Slot 1 │ Slot 2 │ Slot 3 │ Slot 4 │ Slot 5 │
│ torrent-search │ (empty) │ (empty) │ (empty) │ (empty) │
│ ✓ active │ │ │ │ │
└──────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┘
Active: 1/5
After installing both MCPs:
┌──────────────────┬──────────────────┬──────────────────┬──────────────────┬──────────────────┐
│ Slot 1 │ Slot 2 │ Slot 3 │ Slot 4 │ Slot 5 │
│ torrent-search │ memory │ sequential- │ (empty) │ (empty) │
│ ✓ active │ ✓ active │ thinking │ │ │
│ │ │ ✓ active │ │ │
└──────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┘
Active: 3/5 (2 slots remaining for GitHub MCP + Brave Search)
### 11.3 Post-Installation Usage Flow (How I Would Use These MCPs)
DGRM_25
---
## Summary: Design at a Glance
Design Summary — What This Document Specifies
This is a pure design document. Nothing was created, modified, or installed. The design covers:
server-memory (v0.6.3) — 9 tools, persistent JSON knowledge graph, needs MEMORY_FILE_PATH env var, Node.js/npx
server-sequential-thinking (v0.6.2) — 1 tool, in-memory stateless, no env config, Node.js/npx
Package-Manager Abstraction Module — 5 components (Detector, Classifier, Resolver, Executor, Verifier) with fallback chains: npx → npm → pnpm (Node.js) and uvx → uv (Python)
7-phase installation pipeline — Detect → Classify → Resolve → Execute → Import → Activate → Verify
System reality — All 6 package managers detected on this machine: node v24.14.1, npm 11.1.1, npx 11.11.0, pnpm 11.1.1, uv 0.11.6, uvx 0.11.6
Slot management — Would bring active MCPs from 1/5 to 3/5, leaving 2 slots for GitHub + Brave Search
---
Angela — this is the complete detailed design. Nothing was modified, nothing was created, nothing was installed. This is pure architecture: flow diagrams, sequence diagrams, state machines, data schemas, error handling, and integration mapping. When you're ready to actually execute the installation, just say the word and I'll run the real external_mcp_import + external_mcp_set_active + external_mcp_wait pipeline.