# 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:

```bash
export LINKA_RUNTIME_URL=http://127.0.0.1:3000
```

You can also tune the lightweight cache with `LINKA_RUNTIME_CACHE_TTL_MS`:

```bash
export LINKA_RUNTIME_CACHE_TTL_MS=1000
```

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

```bash
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

```bash
npm install
```

## Run

```bash
npm start
```

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

## Test

```bash
npm test
```

To run lint and tests together:

```bash
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:

```bash
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

```text
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