API Reference

Complete reference for the kinetic-context API and MCP server tools.

About kinetic-context Tools

Important: kinetic-context tools are designed for asking usage questions about dependencies by analyzing their source code. They are not for querying dependency metadata (like package.json contents). The system uses OpenCode to analyze the actual source code of dependencies and provide intelligent answers about usage patterns, APIs, and best practices.

MCP Server Endpoint

Base URL: http://localhost:7167/mcp

All MCP tools are accessible through this endpoint using the Model Context Protocol.

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.

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

Parameters

Returns

Array of dependency objects:

Array<{
  identifier: string;
  tag: string;
}>

Example Request

{
  "tool": "list_project_dependencies",
  "parameters": {
    "project_identifier": "my-project"
  }
}

Example Response

[
  {
    "identifier": "zod",
    "tag": "v3.22.0"
  },
  {
    "identifier": "@hookform/resolvers",
    "tag": "master"
  }
]

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.

Use cases:

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

Parameters

None

Returns

Array of package objects with identifiers, display names, and package managers:

Array<{
  identifier: string;
  display_name: string;
  package_manager: string;
}>

Example Request

{
  "tool": "list_dependencies",
  "parameters": {}
}

Example Response

[
  "zod",
  "@hookform/resolvers",
  "react",
  "@tanstack/react-query"
]

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

Returns

JSON object containing:

• response (string): The answer to the query
• sessionId (string): A session identifier that can be used in subsequent queries to continue the conversation

Example Request

{
  "tool": "query_dependency",
  "parameters": {
    "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"
}

Behavior

1. Source Code Analysis: The system clones the dependency repository (if not already available) and analyzes the actual source code using OpenCode.

2. If project_identifier is provided:

   • Looks up the project configuration
   • Finds the dependency in the project's dependencies
   • Checks out the specified tag (if different from default)
   • Queries at that specific version

3. If project_identifier is not provided:

   • Uses the package's default_tag
   • Queries the dependency at the default version

4. If sessionId is provided:

   • Continues the conversation from the previous session
   • Maintains context from earlier queries in the same session
   • Allows for follow-up questions and clarifications

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:

1. First ask about zod: query_dependency with query "How do I create validation schemas with zod?"
2. Then ask about react-hook-form: query_dependency with query "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

This approach provides better results than trying to ask about multiple dependencies in a single query.

HTTP API

The web application also exposes HTTP endpoints for programmatic access.

Health Check

GET /health

Returns the health status of the server.

Response

{
  "status": "ok"
}

Web UI

GET /

Serves the web application interface.

MCP Endpoint

POST /mcp

MCP protocol endpoint. Accepts MCP protocol messages and returns responses.

Error Responses

All endpoints may return error responses in the following format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

• DEPENDENCY_NOT_FOUND - The specified dependency identifier doesn't exist
• PROJECT_NOT_FOUND - The specified project identifier doesn't exist
• INVALID_QUERY - The query parameter is missing or invalid
• OPENCODE_ERROR - Error communicating with OpenCode service
• GIT_ERROR - Error cloning or checking out repository

Rate Limiting

Currently, there are no rate limits enforced. However, be mindful of:

• OpenCode API rate limits (depends on your provider)
• Git operations (cloning large repositories)
• System resources (memory, CPU)

Authentication

Currently, the MCP server and API do not require authentication as they are designed to run locally. For production deployments, consider:

• Adding authentication middleware
• Using reverse proxy with authentication
• Network-level security (firewall rules)

Versioning

The API follows semantic versioning. Breaking changes will be indicated by version increments in the Docker image tags.

Current version: See DockerHub tags for available versions.