Linka MCP Next

Clean MCP base for the next Linka generation.

This repository is intentionally separate from the existing Linka desktop runtime. It starts with a small stdio MCP server and keeps the first surface area narrow:

• no Electron shell
• no mobile UI
• no native input helpers
• no historical bridge or teach runtime copied over wholesale

The goal is to provide a maintainable MCP foundation that can grow from a clear contract instead of inheriting the full desktop stack.

If you want to connect it to a live Linka desktop runtime, set LINKA_RUNTIME_URL to the desktop app's local status endpoint, for example:

export LINKA_RUNTIME_URL=http://127.0.0.1:3000

You can also tune the lightweight cache with LINKA_RUNTIME_CACHE_TTL_MS:

export LINKA_RUNTIME_CACHE_TTL_MS=1000

Teach diagnostics use the same runtime URL and a dedicated timeout:

export LINKA_TEACH_TIMEOUT_MS=2000

What it exposes

• linka-status: runtime and environment snapshot
• linka-manifest: static project manifest
• linka-migration: prioritized migration guidance from the old repo
• linka-bridge-status: bridge state, connected clients, and recent activity
• linka-session-diagnostics: pairing, session, and activity diagnostics
• linka-health-check: runtime-adapter health summary
• linka-control-policy: policy map for future controlled actions
• linka-control-plan-action: dry-run-only action planning tool
• linka-teach-status: Teach exposure and mode snapshot
• linka-teach-latest: latest known Teach artifact summary
• linka-teach-list-artifacts: compact Teach artifact listing
• linka-teach-library-summary: Teach library overview
• linka-teach-get-artifact: bounded Teach artifact detail by id
• linka-teach-diagnostics: Teach capability and diagnostics bundle
• linka-teach-explain-artifact: read-only explanation of a Teach artifact
• linka-teach-run-artifact-dry-run: dry-run execution plan for a Teach artifact
• linka-teach-start: confirmation-gated Teach recording start
• linka-teach-stop: confirmation-gated Teach recording stop

Contract Layer

Runtime and Teach diagnostics are versioned contracts, not ad hoc payloads.

• Runtime status schema: src/contracts/runtime-status.schema.json
• Teach status schema: src/contracts/teach-status.schema.json
• Teach artifacts schema: src/contracts/teach-artifacts.schema.json
• Teach artifact detail schema: src/contracts/teach-artifact-detail.schema.json
• Teach library schema: src/contracts/teach-library.schema.json
• Teach explain-artifact schema: src/contracts/teach-explain-artifact.schema.json
• Teach run-artifact dry-run schema: src/contracts/teach-run-artifact-dry-run.schema.json
• Teach start action schema: src/contracts/teach-start-action.schema.json
• Teach stop action schema: src/contracts/teach-stop-action.schema.json
• System overview schema: src/contracts/system-overview.schema.json
• Version fields: runtimeContractVersion and teachContractVersion
• Teach artifacts version field: teachArtifactsContractVersion
• Teach artifact detail version field: teachArtifactDetailContractVersion
• Teach library version field: teachLibraryContractVersion
• Teach explain-artifact version field: teachExplainArtifactContractVersion
• Teach run-artifact dry-run version field: teachRunArtifactDryRunContractVersion
• Teach start action version field: teachStartActionContractVersion
• Teach stop action version field: teachStopActionContractVersion
• System overview version field: systemOverviewContractVersion

The HTTP adapters validate incoming /api/status, /api/teach/status, /api/teach/artifacts, and /api/teach/artifacts/:id payloads before exposing them through MCP. Validation failures become warnings, malformed payloads are normalized into safe null-filled snapshots, and MCP responses continue to resolve instead of crashing.

Versioning policy:

• Contract versions start at 1.0.0
• Compatible additive changes keep the current major version
• Breaking field removals or type changes require a new major version
• MCP resources and diagnostics include the active contract version alongside the snapshot

Resources

Resources are read-only and intended for agent context, not actions.

• linka://runtime/status
• linka://runtime/bridge
• linka://runtime/sessions
• linka://runtime/health
• linka://runtime/session
• linka://teach/status
• linka://teach/latest
• linka://teach/artifacts
• linka://teach/library
• linka://teach/capabilities
• linka://system/overview

Requirements

• Node.js 20 or newer

Install

npm install

Run

npm start

The server runs over stdio, which is the simplest shape for MCP clients that spawn local tools.

Test

npm test

To run lint and tests together:

npm run check

Connecting to live Linka

The MCP base auto-selects an adapter:

• If LINKA_RUNTIME_URL is set, it uses the HTTP runtime adapter and fetches GET /api/status.
• If LINKA_RUNTIME_URL is not set, it uses the stub adapter.
• Both tools and resources share the same in-memory cache, so repeated reads within the TTL do not re-fetch Linka.
• linka://runtime/session is the authoritative session snapshot for active session state.
• Teach uses GET /api/teach/status when LINKA_RUNTIME_URL is set.
• Teach artifact listing uses GET /api/teach/artifacts when LINKA_RUNTIME_URL is set.
• Teach artifact detail uses GET /api/teach/artifacts/:id when LINKA_RUNTIME_URL is set.
• If the Teach endpoint is missing or fails, the MCP layer falls back to a stub snapshot with warnings.
• The Teach HTTP adapter uses LINKA_TEACH_TIMEOUT_MS when set.

Example:

LINKA_RUNTIME_URL=http://127.0.0.1:3000 npm start

Limitations:

• The HTTP adapter is read-only for observation, but linka-teach-start and linka-teach-stop can now perform controlled Teach recording mutations when confirmation is supplied.
• The HTTP adapter depends on the Linka desktop runtime exposing /api/status.
• If Linka is offline or the endpoint is unavailable, the adapter returns degraded diagnostics instead of crashing.
• The cache is intentionally lightweight and process-local.
• Resources expose context only; they do not mutate runtime state.
• Some session fields are derived from existing runtime state; if the runtime cannot prove them, they are returned as null.
• Teach is also read-only and only describes the current capability surface.
• Teach artifact listing is read-only and compact; it does not read markdown or screenshot contents by default.
• Teach artifact detail is read-only and bounded; it does not expose raw screenshots or binary data.
• Teach fields may still be null when the runtime cannot prove them.
• Teach artifact listing fields may still be null when the runtime cannot prove them.
• Teach artifact detail previews are capped at 20 actions.
• Contract validation is warning-only so the MCP layer stays available even if the desktop runtime drifts.
• The schema files are the source of truth for required, optional, and nullable fields.
• Backward-compatible additions are allowed; removals or type changes must go through a new contract version.
• Control-plane planning still exists, and the Teach start/stop tools are the first confirmation-gated control actions.
• linka-control-policy exposes the future action policy map and confirmation levels.
• linka-control-plan-action returns the safe plan, required confirmation level, cache invalidation targets, and an in-memory audit id without executing anything.
• Teach archive and Teach run execution remain out of scope.

Architecture

src/
  config.js      runtime metadata and defaults
  manifest.js    manifest, status, and migration snapshots
  adapters/      runtime adapter stubs and future runtime bridges
  contracts/     JSON schemas and contract validation helpers
  runtime/       cache and snapshot sharing
  control/       control-policy, dry-run planning, and audit scaffolding
  teach/         Teach cache and read-only catalogs
  resources.js   MCP resource catalog
  tools.js       MCP tool catalog and responses
  server.js      MCP registration and transport wiring
  index.js       process entrypoint
tests/
  *.test.js      pure-function and module-load tests

Tool contract

• linka-status: reports runtime metadata such as Node version, PID, and platform
• linka-manifest: reports the base repo contract and boundaries
• linka-migration: reports the recommended migration order from the desktop repo
• linka-bridge-status: reports bridge message counts, connected clients, and warnings
• linka-session-diagnostics: reports pairing/session state and last activity
• linka-health-check: reports whether the runtime adapter looks healthy or degraded
• linka-control-policy: reports the current control policy map for future actions
• linka-control-plan-action: reports what would be required to safely perform a future control action
• linka://runtime/status: read-only runtime snapshot for agent context
• linka://runtime/bridge: read-only bridge snapshot for agent context
• linka://runtime/sessions: read-only session snapshot for agent context
• linka://runtime/health: read-only health snapshot for agent context
• linka://runtime/session: complete active session snapshot for agent context
• linka-teach-status: reports whether Teach is exposed to MCP and what mode it is in
• linka-teach-latest: reports the latest known Teach artifact summary
• linka-teach-list-artifacts: reports the compact Teach artifact listing
• linka-teach-library-summary: reports the Teach library overview
• linka-teach-get-artifact: reports a bounded detail view for one Teach artifact id
• linka-teach-diagnostics: reports Teach capabilities, artifacts, and limitations
• linka-teach-explain-artifact: reports a safe, read-only explanation of a known Teach artifact
• linka-teach-run-artifact-dry-run: reports a dry-run execution plan for a Teach artifact
• linka://teach/status: read-only Teach status for agent context
• linka://teach/latest: read-only Teach artifact summary for agent context
• linka://teach/artifacts: read-only Teach artifact listing for agent context
• linka://teach/library: read-only Teach library overview for agent context
• linka://teach/capabilities: read-only Teach capability map for agent context
• linka://system/overview: consolidated runtime + Teach system snapshot for agent context, including the Teach library summary
• linka-control-policy and linka-control-plan-action are planning-only scaffolding for Phase 7A; they do not execute actions
• linka-teach-explain-artifact reuses the existing artifact detail cache and only derives an explanation from metadata and bounded action previews
• linka-teach-run-artifact-dry-run reuses the artifact detail cache and explanation metadata to plan future execution, but it never executes, mutates, or sends input

Why this repo exists

The existing Linka repository is a full desktop product with Electron, native input backends, pairing, bridge flows, and macOS-first teach capture. That is useful reference material, but it is not the cleanest starting point for an MCP-native base.

This repo stays focused on the next layer:

• MCP tool registration
• structured responses
• small, testable helpers
• explicit migration boundaries