MCP Integration

Integrate Knowns with AI assistants for seamless development workflows.

v0.20 consolidates 46 individual MCP tools into 10 domain-grouped tools with action-based dispatch. This reduces context overhead while maintaining full feature parity. The release also adds AI permission guards and MCP audit trails.

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. Knowns implements an MCP server that allows AI to read and manage your tasks and documentation directly.

Session Initialization (Critical)

At the START of every MCP session, run these tools to set the project context:

// 1. Detect available projects
project({ action: "detect" })

// 2. Set the active project
project({ action: "set", projectRoot: "/path/to/project" })

// 3. Check project readiness and capabilities
project({ action: "status" })

Why? MCP servers (especially global configs like Antigravity/Gemini) don't know which project to work with. Without setting the project, operations will fail or affect the wrong directory.

Support Matrix

Setup

Option A: Auto Setup (Recommended)

knowns mcp setup

What happens:

• Creates .mcp.json in your project for Claude Code auto-discovery
• Registers the Knowns MCP server with the Claude CLI if installed
• Reminds you to restart your AI assistant to load the server

Variations

• knowns mcp setup --project — only create/update .mcp.json in this project
• knowns mcp setup --global — only register with Claude Code CLI

Option B: Manual Setup

Platform Configs

Claude Code: .mcp.json (Project-level)

{
  "mcpServers": {
    "knowns": {
      "command": "knowns",
      "args": ["mcp"]
    }
  }
}

Kiro: .kiro/settings/mcp.json

{
  "mcpServers": {
    "knowns": {
      "command": "knowns",
      "args": ["mcp"]
    }
  }
}

Antigravity: ~/.gemini/antigravity/mcp_config.json (Global)

{
  "mcpServers": {
    "knowns": {
      "command": "knowns",
      "args": ["mcp"]
    }
  }
}

Note: Antigravity uses global config. Use project({ action: "detect" }) and project({ action: "set" }) at session start.

Gemini CLI: ~/.gemini/settings.json (Global)

{
  "mcpServers": {
    "knowns": {
      "command": "knowns",
      "args": ["mcp"]
    }
  }
}

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "knowns": {
      "command": "knowns",
      "args": ["mcp"]
    }
  }
}

Continue: .continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "knowns",
        "transport": {
          "type": "stdio",
          "command": "knowns",
          "args": ["mcp"]
        }
      }
    ]
  }
}

CLI Commands

# Auto-generate MCP config
knowns mcp setup

# Only create project-level .mcp.json
knowns mcp setup --project

# Only register globally with Claude Code
knowns mcp setup --global

Available MCP Tools (v0.20 Consolidated)

In v0.20, tools are grouped by domain with action-based dispatch. Instead of 46 separate tools, there are now 10 domain tools.

Project

Tasks

Docs

Memory (Persistent)

Search

Time

Templates

Code Intelligence

Validation

AI Permission Model (v0.20)

Knowns now includes a capability-based permission system for AI actions:

// Check permissions via project status
project({ action: "status" })
// Returns: permissions.allowedCapabilities, permissions.deniedCapabilities

Permission presets control what AI agents can do:

• read-only: Only read operations allowed
• read-write-no-delete: Read and write, but no deletions (default)
• full-access: All operations allowed

MCP Audit Trail (v0.20)

All MCP tool calls are now audited with structured events. Use project({ action: "status" }) to check audit capabilities.

Usage

Once configured, your AI assistant can access Knowns data automatically.

Example Conversation

You: "Start working on task abc123"

Claude: [Reads task via MCP]
tasks({ action: "get", taskId: "abc123" })

"I see task 'Add user authentication' with these acceptance criteria:
- User can login with email/password
- JWT token is returned on success
- Invalid credentials return 401

The description references @doc/patterns/auth. Let me check that..."

docs({ action: "get", path: "patterns/auth", smart: true })

"Got it! Starting timer and beginning implementation..."

time({ action: "start", taskId: "abc123" })

MCP vs CLI

Recommendation: Use MCP for all operations when available.

Full Feature Parity

Large Document Workflow:

// Step 1: Use smart mode (recommended) - auto-handles size
docs({ action: "get", path: "readme", smart: true })
// Small doc → returns full content
// Large doc → returns stats + TOC

// Step 2: Read specific section (if large)
docs({ action: "get", path: "readme", section: "2" })

Example: Full Task Workflow via MCP

// 0. Session init (required for global MCP configs)
project({ action: "detect" })
project({ action: "set", projectRoot: "/path/to/project" })

// 1. Get task
tasks({ action: "get", taskId: "abc123" })

// 2. Take task
tasks({ action: "update", taskId: "abc123", status: "in-progress", assignee: "@me" })

// 3. Start timer
time({ action: "start", taskId: "abc123" })

// 4. Set implementation plan
tasks({ action: "update", taskId: "abc123", plan: "1. Research\n2. Implement\n3. Test" })

// 5. Check AC after completing
tasks({ action: "update", taskId: "abc123", checkAc: [1] })

// 6. Append progress notes
tasks({ action: "update", taskId: "abc123", appendNotes: "✓ Completed: login feature" })

// 7. Stop timer
time({ action: "stop", taskId: "abc123" })

// 8. Mark done
tasks({ action: "update", taskId: "abc123", status: "done" })

Benefits

Zero Context Loss

• AI reads your docs directly - no copy-paste
• References (@doc/..., @task-42) are resolved automatically
• Project patterns are always available

Consistent Implementations

• AI follows your documented patterns every time
• Same conventions across all sessions
• No more "how does your auth work?" questions

Perfect Memory

• Documentation persists between sessions
• AI can reference any past decision
• Knowledge doesn't live in chat history

Time Tracking Integration

• AI can start/stop timers automatically
• Track time spent on each task
• Generate reports for retrospectives

Troubleshooting

MCP server not responding

• Verify installation: knowns --version
• Run knowns mcp setup again
• Restart your AI assistant

Project not detected

# Check project is initialized
knowns init

# For global configs, use session init
project({ action: "detect" })
project({ action: "set", projectRoot: "/path" })

Tools not appearing

knowns init          # ensure project initialized
knowns mcp --stdio   # start MCP server

Alternative: --plain Output

If MCP is not available, use --plain flag for AI-readable output:

knowns task pdyd2e --plain | pbcopy
knowns doc "auth-pattern" --smart --plain

Then paste into any AI assistant.

Resources

• MCP Protocol Specification
• Claude Desktop Configuration