# C10:OS Perplexity Local MCP Bridge Specification

Status: Design choice locked
Date: 2026-06-22
Publisher URL: https://c10-os.com/perplexity-local-mcp-spec.html

## Decision

C10:OS will integrate with Perplexity through a local MCP bridge.

The bridge has two sides:

1. Read path: Perplexity calls a local, read-only MCP server to retrieve sanitized C10 context for research.
2. Write-back path: Perplexity can save selected reports back into C10 through explicit, confirmation-gated MCP write tools.

Remote C10 APIs and remote MCP are deferred. They are more powerful for multi-device access, but they expose a larger network attack surface. The local MCP design keeps credentials and raw C10 state on the Mac.

## Goals

- Give Perplexity Deep Research enough C10 context to reason accurately about the system.
- Keep C10 credentials local.
- Avoid exposing raw databases, `.env`, tokens, private reports, or unrestricted filesystem reads.
- Let useful Perplexity research reports return to C10 as durable artifacts.
- Record write-back intent in the WHY chain.

## Non-Goals

- No direct Perplexity access to arbitrary files.
- No public unauthenticated endpoint.
- No direct mutation of C10 state from research mode.
- No raw database dump export.
- No credential passthrough to Perplexity.

## Architecture

```text
Perplexity Mac App
  |
  | MCP tool calls
  v
C10 Local MCP Server
  |
  | allowlisted readers / explicit writers
  v
~/.C10/
  |-- docs and sanitized context
  |-- c10 CLI
  |-- registries
  |-- WHY chain
  `-- research inbox
```

## Security Model

The local MCP server is the trust boundary.

Read tools must:

- Run locally only.
- Expose summaries or bounded excerpts, not broad filesystem access.
- Use path allowlists.
- Deny known secret locations and sensitive file patterns.
- Redact tokens, keys, passwords, cookies, and private report credentials.
- Log each request.

Write tools must:

- Require explicit user confirmation in Perplexity.
- Require a `why` field.
- Write only to an allowlisted C10 research inbox.
- Never overwrite existing files without creating a new version.
- Append a WHY entry or queue one for review.
- Preserve source URLs and timestamps.

## Read Tool Surface

Initial read tools:

- `c10_overview()`: returns the compact C10 identity, architecture, and current source brief.
- `c10_search(query, scope?)`: searches allowlisted C10 docs and returns ranked excerpts.
- `c10_read_doc(id)`: reads a specific allowlisted document by stable id.
- `c10_services()`: returns sanitized service registry summary.
- `c10_halls(status?, query?)`: returns sanitized hall summaries.
- `c10_recent_why(limit?)`: returns recent non-sensitive WHY entries.
- `c10_bj_search(query)`: searches sanitized bj0 summaries.

The tool set should prefer stable ids over raw paths.

## Denylist

The MCP must deny reads from:

- `.env`
- files containing `TOKEN`, `KEY`, `SECRET`, `PASS`, `COOKIE`, `PRIVATE`
- SQLite databases and WAL/SHM files unless queried through a sanitizer
- private reports and admin-only briefs
- raw credential files
- SSH keys, GPG keys, certificates, browser profiles, and local keychains
- `node_modules`, build caches, logs with secrets, and generated binaries

## Write Tool Surface

Initial write tools:

- `c10_save_research_report(title, markdown, source_urls, why, tags?)`
- `c10_capture_research_finding(summary, source_url, why, tags?)`
- `c10_create_bj_from_report(title, markdown, why, priority?)`

Default destination:

```text
~/.C10/_INBOX_/perplexity/
```

Each saved report should include front matter:

```yaml
---
source: perplexity
created_at: ISO-8601 timestamp
title: report title
why: user supplied reason
tags: []
source_urls: []
---
```

## Perplexity Usage Pattern

1. Enable the C10 Local MCP connector in the Perplexity Mac app.
2. Select the C10 MCP as a source before a C10-aware research session.
3. Ask Deep Research to use C10 MCP context as internal ground truth.
4. Review the result.
5. If worth keeping, ask Perplexity to save the report back to C10.
6. Confirm the write action.

Suggested instruction:

```text
Use the C10 Local MCP source as ground truth for C10:OS.
Use web research for external facts and cite those sources.
Separate C10-local facts from external research.
Do not infer credentials, private state, or unavailable files.
When I ask to save a report, call the C10 write-back tool with a clear WHY.
```

## Implementation Phases

Phase 1: Read-only local MCP

- Implement allowlisted docs and search.
- Expose overview, services, halls, doc read, and search tools.
- Add redaction tests.
- Add request logging.

Phase 2: Write-back inbox

- Add `c10_save_research_report`.
- Require explicit `why`.
- Store markdown reports under `_INBOX_/perplexity/`.
- Append or queue WHY entries.

Phase 3: Capture and bj0 promotion

- Add finding capture and bj creation tools.
- Add classification hooks.
- Add duplicate detection.

Phase 4: Optional remote design review

- Re-evaluate remote MCP or Cloudflare Access API only after local MCP proves useful.

## Acceptance Criteria

- Perplexity can answer C10 architecture questions using local C10 context.
- Perplexity cannot read `.env` or any denied secret file.
- Perplexity cannot browse arbitrary paths.
- Perplexity can save a reviewed report into C10 only after confirmation.
- Saved reports include title, timestamp, source URLs, tags, and WHY.
- Every tool call is logged.
- Redaction tests cover common secret formats.