Orchestration Plan 3

Scope: Build the forge-discovery MCP server — a read-only MCP that gives agents structured access to Uvilo OS project and skill data without filesystem grepping (Spec §3).

Spec: Orchestration Spec

Prior plan: Plan 2

---

Task 1 — Scaffold the forge-discovery MCP Server

The Discovery MCP is a standalone MCP server configured in librechat.yaml and available to agents via the standard MCP tool interface (Spec §3.1). It reads the filesystem structure and returns structured data.

1. Create directory: mcp-servers/forge-discovery/
2. Initialize a TypeScript project: package.json, tsconfig.json
3. Install dependencies: @modelcontextprotocol/sdk, dotenv
4. Create entry point: src/index.ts — MCP server using Streamable HTTP transport
5. Add the MCP server to Forge/Configs/LibreChat_Service/librechat.yaml as an MCP server entry:

   mcpServers:
     forge-discovery:
       url: http://forge-discovery.railway.internal:3000/mcp
       # or appropriate Railway internal URL

6. Verify the MCP server connects and tools are available to agents

Deliverable: Scaffolded MCP server that connects to LibreChat and registers its tools.

---

Task 2 — Implement Project Discovery Tools

Spec §3.1 defines these project-related tools: list_departments, list_projects, find_project, get_project_phase, get_project_files.

1. list_departments: Read top-level directories in the repo, return each with its README.md summary. A department is a root-level folder with README.md, AGENTS.md, Projects/, Skills/.
2. list_projects(department: string): Read {DEPT}/Projects/ directories, return each with name, current phase (from {Project}_Phase.md), and file list.
3. find_project(query: string): Fuzzy match across all departments for a project name. Support partial or misspelled names. Return best match with department, name, phase.
4. get_project_phase(project: string, department: string): Read the {Project}_Phase.md file, return the current phase value.
5. get_project_files(project: string, department: string): List all files in the project directory with metadata (name, type from frontmatter, status from frontmatter).

Each tool returns structured JSON. The server reads the filesystem at /workspace/erik/uvilo-os/ (the repo mount point). All reads are read-only — no mutations.

Deliverable: Five project discovery tools implemented and tested.

---

Task 3 — Implement Skill Discovery Tools

Spec §3.1 defines these skill-related tools: list_skills, find_skill, get_skill_details.

1. list_skills(department?: string): Read all */Skills/*/SKILL.md files. If department specified, filter to that department. Return skill name, description, department.
2. find_skill(query: string): Fuzzy match on skill name and description across all departments. Return best matches.
3. get_skill_details(skill: string, department?: string): Return the full SKILL.md content for the named skill. If department not specified, search all departments.

Deliverable: Three skill discovery tools implemented and tested.

---

Task 4 — Deploy forge-discovery MCP to Railway

The MCP server runs as a Railway web service, configured in LibreChat’s librechat.yaml.

1. Create Dockerfile for the MCP server
2. Create the Railway service:
   • Name: forge-discovery-mcp
   • Environment variables: REPO_PATH=/workspace/erik/uvilo-os, PORT
3. Deploy and verify:
   • MCP server is reachable at its internal URL
   • LibreChat picks up the MCP configuration
   • Tools appear in agent tool lists
4. Test with an agent: call list_projects and list_skills from a LibreChat chat session

Deliverable: forge-discovery MCP deployed and accessible to LibreChat agents.