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 |
                              +--------+---------+
                                       |
                                       | raw meeting batches
                                       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, and Antigravity.
• It exports raw transcript material into pm-state/ 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 raw transcript batches into pm-state/ingest/

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
• raw ingest batches in pm-state/ingest/
• 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
• ./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
• 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.
Bootstrap pm-state, ingest my latest 20 meetings, and show blockers plus next actions.

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 run the PM pipeline and summarize decisions, actions, blockers, and next steps.

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.
Packetize the last 10 meetings and give me 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

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 config
├── .vscode/               VS Code config
├── kytip                  kytip-pm launcher
└── pm-state/              PM truth owned by kytip-pm

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]