# AGENTS.md — 1mcp.in

Read this file before changing code. It is the architecture and delivery contract for the public `1mcp.in` repository.

## Product Scope

`1mcp.in` is a local-first MCP hub made of:

- `mach1` — the local router with a 3-tool kernel
- `web-ui` — SvelteKit + Tauri Hub UI

The `packages/registry-index/` directory holds the verified marketplace catalog.

This repository does **not** contain the private Team Pro backend or web app.

## Current Architecture

```
services/
  mach1/
    cmd/
      mach1/              router binary (stdio server)
      mach1cli/           CLI tool (install, connect, config, rules)
    internal/
      catalog/            bundled .mcpb catalog loading
      clients/            AI client config discovery + connect
      install/            install pipeline (bundle-based)
      kernel/             3-tool kernel: mem_mcp, find_mount_mcp, call_tool
      manifest/           .mcpb manifest parsing & validation
      observability/      local metrics helpers
      paths/              well-known path resolution
      proto/              JSON-RPC 2.0 message types
      registry/           local SQLite install registry
      router/             MCP server (stdio) + rule generation
      secrets/            OS keychain credential storage
      security/           redaction helpers
      semantic/           BM25 tool-to-query ranking
      supervisor/         MCP child process lifecycle
      transport/          MCP transport layer
      version/            build version
  web-ui/
    src/                  Svelte pages, components, stores
    src-tauri/            Tauri Rust backend
packages/
  registry-index/         verified marketplace catalog (SHA256 pinned)
```

## 3-Tool Kernel

The router exposes exactly three tools to AI clients:

| Tool | Purpose |
|---|---|
| `mem_mcp` | Check what's already mounted in this session. Returns `{found: true, name, description, tools}` or `{found: false}`. |
| `find_mount_mcp` | Ask "I need to X" — BM25 ranks all 52 catalog entries, mounts the best match, returns its tools. If the MCP needs credentials, returns `needs_credentials` before mounting. |
| `call_tool` | Execute a tool on an already-mounted MCP. |

This replaces the old transparent proxy model.

## Supported Clients

| Client | Config Key | Config Path |
|---|---|---|
| Cursor | `mcpServers` | `~/.cursor/mcp.json` |
| VS Code / GitHub Copilot | `servers` | `~/.vscode/mcp.json` |
| Windsurf | `mcpServers` | `~/.codeium/windsurf/mcp_config.json` |
| OpenCode | `mcp` | `~/.config/opencode/opencode.json` |

Claude Desktop, Claude Code, and Codex are not supported.

## Enforceable Rules

1. Keep `mach1` as the single local entry point for AI clients.
2. Do not bypass the registry catalog or modify verified SHA256 entries in `packages/registry-index/` without maintainer approval.
3. Never log raw secrets, tokens, or password-reset identifiers.
4. Return, wrap, or explicitly handle every error. Do not silently drop failures.
5. Do not add future-state docs that describe unbuilt features as present behavior.
6. Do not commit private Team Pro code or claim this repository contains it.
7. Preserve warm-path performance. Kernel changes must not regress the 1-2ms warm call baseline or the sub-30MB idle target.
8. Prefer one clear responsibility per package. Avoid cross-boundary imports.
9. Remove dead code instead of leaving commented-out blocks or dormant scaffolding.
10. Use maintainer review for marketplace trust changes. Automation must not auto-approve catalog entries.

## Working Notes For Agents

- The 3-tool kernel is in `services/mach1/internal/kernel/`. Each tool is one file.
- Rule instructions are generated by `router.BuildInstructions()` — single source of truth.
- Config JSON is generated client-side (Go CLI or Svelte UI) from `mach1` binary path.
- Windsurf uses `~/.codeium/windsurf/mcp_config.json` — note the path difference.
- OpenCode stores credentials in the same file as MCP config (opencode.json).
- E2e harness runs 52 kernel tests at `services/mach1/internal/kernel/catalog_test.go`.
- `mach1cli` commands are pipe-friendly: `mach1cli config cursor | clip` works.
- The `go vet ./...` and `go test ./...` must pass before committing.
