MCP Server

kinetic-context exposes a Model Context Protocol (MCP) server that AI coding tools can connect to for asking usage questions about dependencies.

What is kinetic-context?

kinetic-context is designed to help AI agents answer questions about how to use dependencies by analyzing their source code. It's not for querying dependency metadata (like package.json contents), but rather for asking questions like:

• "How do I validate forms with zod?"
• "What's the best way to use react-hook-form with TypeScript?"
• "How do I integrate zod with react-hook-form?"

The system clones dependency repositories and uses OpenCode to analyze the actual source code and provide intelligent answers based on the implementation.

What is MCP?

The Model Context Protocol (MCP) is a protocol that enables AI assistants to securely access external data sources and tools. kinetic-context implements an MCP server that provides information about open-source dependencies by analyzing their source code.

Server Endpoint

The MCP server is exposed at:

http://localhost:7167/mcp

(Or whatever port you've configured in your Docker Compose setup)

Available Tools

The MCP server provides the following tools:

list_project_dependencies

Lists all dependencies configured for a specific project. These dependencies can then be queried using query_dependency to ask usage questions about how to use them.

Parameters:

• project_identifier (required): The identifier of the project (must match a project config file name)

Returns: Array of dependency objects with their identifiers and tags

Example:

{
  "project_identifier": "my-project"
}

Note: This tool lists which dependencies are configured for a project. To ask questions about how to use these dependencies, use query_dependency instead.

list_dependencies

Lists all available dependencies that have been configured in the system. These dependencies can then be queried using query_dependency to ask usage questions about how to use them.

Parameters: None

Returns: Array of all package identifiers with their display names and package managers

Use case: AI agents can use this to:

• See what dependencies are available to ask questions about
• Inform users if they want to ask about a dependency that isn't configured for their project
• Get the correct package identifier to use with query_dependency

query_dependency

Ask questions about how to use a dependency. This tool analyzes the dependency's source code using OpenCode to provide intelligent answers about usage patterns, APIs, and best practices.

Important: This tool is for asking usage questions (e.g., "How do I validate forms with zod?"), not for querying dependency metadata (like package.json contents). The system analyzes the actual source code of the dependency to answer your questions.

Parameters:

• dependency_identifier (required): The identifier of the dependency to query (use list_dependencies to find the correct identifier)
• query (required): The question to ask about how to use the dependency
• project_identifier (optional): If provided, the system will checkout the specific tag configured for this project before querying
• sessionId (optional): Session ID to continue a previous conversation. If provided, the query will be added to the existing session, allowing for follow-up questions and conversation continuity.
• timeout (optional): Timeout in seconds. Default is 180 (3 minutes). Only set this if the user has agreed to a different timeout.

Returns: JSON object containing:

• response: The answer to the query based on analysis of the dependency's source code
• sessionId: A session identifier that can be used in subsequent queries to continue the conversation

Example:

{
  "dependency_identifier": "zod",
  "query": "How do I validate an email address with zod?",
  "project_identifier": "my-project",
  "sessionId": "optional-session-id-from-previous-query"
}

Example Response:

{
  "response": "To validate an email address with zod, you can use the `z.string().email()` method:\n\n```typescript\nimport { z } from 'zod';\n\nconst emailSchema = z.string().email();\n\nconst result = emailSchema.parse('user@example.com');\n```\n\nThis will validate that the string is a valid email format according to RFC 5322.",
  "sessionId": "abc123-session-id"
}

Conversation Continuity: When you provide a sessionId from a previous query, the system maintains context from that conversation, allowing you to ask follow-up questions like "Can you show me an example?" or "What about validation for phone numbers?"

Multiple Dependencies: If you have questions about multiple dependencies, ask each question independently using separate query_dependency calls. For example, if you want to understand how zod and react-hook-form work together, you can:

1. First ask query_dependency about zod: "How do I create validation schemas with zod?"
2. Then ask query_dependency about react-hook-form: "How do I integrate validation with react-hook-form?"
3. If needed, ask follow-up questions to either dependency using the same sessionId to maintain context

Connecting AI Tools

Claude Desktop

To connect Claude Desktop to kinetic-context:

1. Open Claude Desktop settings
2. Add a new MCP server
3. Configure:
   • Name: kinetic-context
   • URL: http://localhost:7167/mcp
   • Type: HTTP

Cursor

To connect Cursor to kinetic-context:

1. Open Cursor settings
2. Navigate to MCP servers
3. Add configuration:

   {
     "name": "kinetic-context",
     "url": "http://localhost:7167/mcp"
   }

Custom Integration

You can integrate with any MCP-compatible client by pointing it to:

http://localhost:7167/mcp

Project Identifier Matching

When using query_dependency with a project_identifier, the system will:

1. Look up the project configuration
2. Find the dependency in the project's dependencies list
3. Checkout the specified tag (if different from default)
4. Query the dependency at that specific version

This allows you to:

• Use different versions of the same dependency in different projects
• Pin specific versions for production
• Test with beta versions in experimental projects

How It Works

1. Package Cloning: When a dependency is first queried, kinetic-context clones the repository to /packages/{identifier}/

2. Version Checkout: If a project identifier is provided and specifies a tag, the system checks out that specific tag

3. Code Analysis: OpenCode analyzes the dependency's codebase to understand its structure and usage

4. Query Processing: Your question is sent to OpenCode along with the relevant code context

5. Response: OpenCode provides an intelligent answer based on the actual code

Best Practices

1. Use project identifiers - Always specify project_identifier when querying to ensure you get answers for the correct version

2. Be specific in queries - More specific questions yield better answers (e.g., "How do I validate a form with zod?" vs. "How does zod work?")

3. Check available dependencies - Use list_dependencies first to see what's available

4. Configure packages first - Make sure packages are configured before querying them

Troubleshooting

Connection Refused

Make sure kinetic-context is running:

kctx status

Dependency Not Found

1. Verify the dependency is configured in /packages/{identifier}.json
2. Check that the repository can be cloned
3. Ensure the identifier matches exactly

Wrong Version

1. Check the project configuration for the dependency tag
2. Verify the tag exists in the repository
3. Try querying without project_identifier to use the default tag

OpenCode Errors

Check the OpenCode configuration and API key in ~/.kctx/opencode/config/opencode.json