kytip-mcp

Local-first MCP server for meeting notes, transcript retrieval, and project-memory handoff into kytip-pm.

Collaborations, ideas, and integrations: [email protected]

                           note sources
         +-----------------------------------------------+
         | Hypernote SQLite | folders | markdown | files |
         +------------------------------+----------------+
                                        |
                                        v
                              +------------------+
                              |    kytip-mcp     |
                              | MCP + connectors |
                              +--------+---------+
                                       |
                                       | immutable raw archive + full batch view
                                       v
                              +------------------+
                              |    pm-state/     |
                              | durable PM truth |
                              +--------+---------+
                                       |
                                       v
                              +------------------+
                              |    kytip-pm      |
                              | ledgers + TUI    |
                              +------------------+

What It Is

kytip-mcp is the adapter layer.

• It connects local note providers.
• It exposes MCP tools and resources to clients such as Cursor, Claude Code, Codex, VS Code, Gemini, Claude Desktop, Antigravity, and GitHub Copilot via the shared root .mcp.json surface.
• It archives complete meeting-owned Hypernote records in pm-state/ and writes a full readable intake view so kytip-pm can do the project-management work.

kytip-pm is the PM runtime.

• npm: https://www.npmjs.com/package/kytip-pm
• It owns the pm-state/ contract.
• It packetizes meetings, refreshes ledgers, reconciles streams, writes the portfolio brief, and drives the terminal UI.

Routing Rules

Use kytip-mcp for:

• MCP transport and client wiring
• filesystem scanning
• Hypernote local SQLite access
• meeting retrieval and context extraction
• session restore and local continuity state
• exporting lossless meeting-owned records into pm-state/ingest/raw/ and readable batches into pm-state/ingest/batches/

Use kytip-pm for:

• bootstrapping pm-state/
• packetizing meetings
• refreshing PM ledgers
• reconciling streams and project pages
• publishing PORTFOLIO_BRIEF.md
• terminal UI and kanban presentation

Do not route these concerns back into kytip-mcp:

• HTML kanban generation
• legacy update_todo-style PM mutation
• direct edits to kytip-pm internals

Agent-facing repo rules also live in AGENTS.md.

What Connects

Current input surface:

• workspace folders and local files
• Hypernote local SQLite databases
• meeting session indexes and transcript slices
• persisted local user/session defaults

Current output surface:

• MCP tools and resources
• immutable raw Hypernote imports in pm-state/ingest/raw/hypernote/<import-id>/
• full readable PMing input batches in pm-state/ingest/batches/
• PM summaries exposed back through MCP resources
• the local ./kytip launcher returned by get_pm_tui

Turnkey Setup

Requirements:

• Node >=22
• npm

Install in a workspace:

npm install kytip-mcp

Bootstrap the workspace:

npx kytip-mcp-init --workspace . --clients all

Or from source in this repo:

npm install
npm run turnkey

What bootstrap writes:

• pm-state/ for PM-owned durable project memory
• .kytip/ for hidden runtime helpers and generated bootstrap notes
• .kytip/bootstrap/ for generated snippets and bootstrap markdown
• .kytip-state/ for MCP-local continuity state
• .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json, .mcp.json for local client wiring
• local launch commands pinned to the exact Node runtime used during bootstrap, so GUI MCP hosts do not need to discover node on PATH
• ./kytip as the intentional workspace TUI launcher created by the kytip-pm contract

What bootstrap does not write:

• no HTML kanban files
• no generated markdown in the visible repo root
• no edits inside the installed kytip-pm package

Portable config templates ship in configs/README.md.

Supported Clients

Turnkey setup writes or prepares configs for:

• Cursor
• Claude Code
• Claude Desktop
• Codex
• GitHub Copilot via .mcp.json
• VS Code
• Gemini CLI
• Antigravity

The packaged templates use npx -y kytip-mcp@latest.

Connecting Notetakers

kytip-mcp is local-first. It does not require a hosted note backend.

Hypernote

Point kytip-mcp at the local SQLite database with either:

• KYTIP_HYPERNOTE_DB_PATH=/absolute/path/to/db.sqlite
• a tool argument such as "db_path": "/absolute/path/to/db.sqlite"

Typical agent instruction:

Use the Hypernote SQLite at /absolute/path/to/db.sqlite.
Archive all of my Hypernote meetings, stage them for PMing, and report the PMing skill handoff.

ingest_hypernote_batch and the Hypernote path in run_pm_pipeline import every meeting by default. Supply a selector, date range, stream, or limit only when intentionally requesting a scoped import; the response reports the applied scope and completeness.

Files and folders

Use scan_workspace or scan_scope to index local markdown, notes, or project folders.

Typical agent instruction:

Scan /absolute/path/to/notes and /absolute/path/to/project.
Then report extracted MCP context. Use a PMing batch or a Hypernote ingest when PM-state processing is required.

What To Say

These prompts work well for agents and help note providers produce cleaner PM output.

Tell your agent

Use kytip-mcp to read my local notes.
Export the raw material into pm-state, then let kytip-pm build the ledgers and open the TUI path.

Use Hypernote at /absolute/path/to/db.sqlite.
Archive and stage the last 10 meetings, then run the PMing skills that produce project-level blockers, owners, and deadlines.

Scan my workspace, then tell me what belongs to kytip-mcp and what belongs to kytip-pm before doing any edits.

Tell your meeting notetaker

Capture decisions, action items, blockers, owners, and due dates explicitly.
Say the project or stream name when the conversation changes topic.
If a task is assigned, state the owner and deadline in the same sentence.

That phrasing makes downstream packetization and ledger refresh much more reliable.

Key MCP Tools

Intake and continuity:

• scan_workspace
• scan_scope
• scan_hypernote
• resume_session
• get_user_state
• set_user_state
• rebuild_index

Meetings:

• list_meeting_sessions
• get_meeting_context
• get_meeting_transcript

PM bridge:

• ensure_pm_workspace
• ingest_hypernote_batch
• packetize_transcript_batch
• refresh_pm_ledgers
• reconcile_pm_streams
• write_portfolio_brief
• run_pm_pipeline
• get_pm_brief
• get_pm_tui

PM bridge behavior:

• ensure_pm_workspace checks PMing capabilities, and when old runtime assets are found it uses kytip-pm@latest to refresh package-owned runtime and skills without overwriting pm-state/.
• ingest_hypernote_batch writes a generated immutable import directory containing manifest.json, schema.json, every selected raw sessions row, and discoverable linked rows keyed by session IDs. It also writes an unclipped readable batch view.
• packetize_transcript_batch delegates safe staging to kytip-pm; base64 content remains exact in the raw archive and is safely elided or sidecarred only in PMing processing artifacts.
• refresh_pm_ledgers, reconcile_pm_streams, and write_portfolio_brief return PMing skill handoffs. MCP does not write those PM-owned artifacts.
• run_pm_pipeline returns awaiting_pming_agent after delegated staging, or pming_stage_blocked if a compatible PMing runtime could not be obtained. An already-created raw archive is not discarded.

Triage and orchestration:

• get_next_actions
• identify_blockers
• identify_risks
• generate_gate_report
• plan_swarm_cycle
• generate_handoff_packet
• ack_handoff

Runtime Layout

workspace/
├── .cursor/               client config
├── .gemini/               client config
├── .kytip/                hidden bootstrap/runtime assets
│   ├── bootstrap/
│   └── kytip_ui.js
├── .kytip-state/          MCP-local continuity state
├── .mcp.json              Claude Code / GitHub Copilot config
├── .vscode/               VS Code config
├── kytip                  kytip-pm launcher
└── pm-state/              PM truth owned by kytip-pm
    └── ingest/
        ├── batches/       full readable input views for PMing
        └── raw/hypernote/ immutable raw meeting-owned imports

This split is intentional:

• kytip-mcp owns the MCP-facing connection layer
• kytip-pm owns PM-state processing and the TUI
• generated bootstrap markdown stays hidden under .kytip/bootstrap/

Repo Layout

• src/: MCP server, connectors, state stores, and PM bridge code
• tests/: Node test suite
• configs/: ready-to-paste client templates
• docs/: supporting implementation notes and maintainer specs

Publishing

Maintainer publication steps are documented in docs/PUBLICATION_SPEC.md.

Core publish commands:

npm test
node --experimental-strip-types src/cli/turnkey.ts --help
npm_config_cache=$PWD/.npm-cache npm pack --dry-run
npm publish --access public

Non-Goals

• no MCP-owned HTML kanban output
• no legacy task-board persistence in local MCP state
• no direct mutation of kytip-pm package internals
• no writes back into Hypernote db.sqlite

Collaboration

For collaborations, integrations, or ideas: [email protected]