# Context7 MCP Server (`c7-mcp-server`)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- Add npm version badge once published: [![NPM Version](https://img.shields.io/npm/v/c7-mcp-server)](https://www.npmjs.com/package/c7-mcp-server) -->

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that acts as a bridge to the [Context7 API](https://context7.com/).

This server allows MCP-compatible clients (like Claude Desktop, IDE plugins, custom applications) to easily interact with Context7's features, including querying documentation context, searching for projects, and retrieving project metadata. It exposes the `c7-mcp-server` command when installed globally.

⚠️ **Important:** All data provided through this server comes directly from the official **Context7 API** (`https://context7.com`). This server simply provides an MCP interface to that API and does not generate or host any content itself.

## Features

Exposes Context7 functionalities via standard MCP capabilities:

*   **Tools:**
    *   `c7_query`: Query the Context7 API for information on a specific topic within a project. Accepts project name, query text, optional format (txt/json), and optional token limit.
    *   `c7_search`: Search for available Context7 projects by keyword. Returns a list of matching projects (title and usable name).
    *   `c7_info`: Get metadata about a specific Context7 project (like source repository, last update, etc.).
*   **Resources:**
    *   `c7_projects_list`: Provides a list of all available (valid) Context7 projects via the URI `context7://projects/list`.

## Installation

### Prerequisites

*   [Node.js](https://nodejs.org/) (Version 18+ recommended)
*   [npm](https://www.npmjs.com/) (usually comes with Node.js) or [Bun](https://bun.sh/)

### Option 1: Install from npm (Recommended for Users)

Once published, install the server globally:

```bash
npm install -g c7-mcp-server
```

This will make the `c7-mcp-server` command available system-wide, allowing MCP clients to launch it.

### Option 2: Install from Source (for Development)

1.  Clone the repository:
    ```bash
    git clone <your-repo-url>
    cd c7-mcp-server
    ```
2.  Install dependencies:
    ```bash
    npm install
    # or if using Bun
    # bun install
    ```
3.  Build the server:
    ```bash
    npm run build
    ```
4.  Link the command locally:
    ```bash
    npm link
    # or if using Bun
    # bun link
    ```

This will make the `c7-mcp-server` command available on your local machine for testing and development.

## Usage

This server is designed to be run by an MCP **client** application, not typically directly by an end-user (except for testing). The client launches the `c7-mcp-server` command, and they communicate over standard input/output (stdio) using the MCP protocol.

### Configuring with Clients (Example: Claude Desktop)

To use this server with a client like Claude Desktop, you need to add it to the client's configuration file.

1.  Ensure `c7-mcp-server` is installed globally (`npm install -g c7-mcp-server`) or linked locally (`npm link`).
2.  Edit the client's configuration file (e.g., `claude_desktop_config.json`):
    *   macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    *   Windows: `%APPDATA%\Claude\claude_desktop_config.json`
3.  Add an entry under `mcpServers`:

    ```json
    {
      "mcpServers": {
        "context7": {
          "command": "c7-mcp-server", // The command name installed/linked
          "args": [] // No arguments needed by default for stdio transport
          // "env": {} // Add environment variables if needed
        }
        // ... other servers ...
      }
    }
    ```
4.  Restart the client application (e.g., Claude Desktop). The client will now launch `c7-mcp-server` in the background and connect to it.

### Testing with MCP Inspector

You can test the server directly using the MCP Inspector:

1.  Make sure `c7-mcp-server` is installed globally or linked locally.
2.  Run the inspector, telling it to execute your server command:

    ```bash
    npx @modelcontextprotocol/inspector c7-mcp-server
    ```

3.  The Inspector UI will open in your browser, connected to your server. Use the "Tools" and "Resources" tabs to interact with the server's capabilities. Check the "Notifications" pane for logs/errors from the server.

## MCP Capabilities Details

### Tools

*   **`c7_query`**
    *   **Description:** Query the Context7 API for information on a specific topic within a project.
    *   **Parameters (`object`):**
        *   `projectname` (string, required): The exact project name (e.g., `nextjs`).
        *   `query` (string, required): The topic/question to query.
        *   `format` (enum: `"txt"` | `"json"`, optional, default: `"txt"`): Output format.
        *   `tokens` (number, optional): Maximum number of tokens for the response.
    *   **Returns:** Text content containing the result from Context7 (either plain text or a JSON string).

*   **`c7_search`**
    *   **Description:** Search for available Context7 projects by keyword.
    *   **Parameters (`object`):**
        *   `term` (string, required): The keyword to search for in project titles.
    *   **Returns:** Text content containing a JSON string array of matching projects, each with `title` and `name` (the usable project name).

*   **`c7_info`**
    *   **Description:** Display metadata about a specific Context7 project.
    *   **Parameters (`object`):**
        *   `projectname` (string, required): The exact project name.
    *   **Returns:** Text content containing a JSON string representation of the project's full metadata.

### Resources

*   **`c7_projects_list`**
    *   **URI:** `context7://projects/list`
    *   **Description:** Provides a list of all available and valid Context7 projects.
    *   **Returns:** Content with `mimeType: "application/json"` containing a JSON string array of project objects.

## Development

1.  Clone the repository.
2.  Install dependencies (`npm install` or `bun install`).
3.  Build the server (`npm run build`). Use `npm run dev` for automatic rebuild and start during development.
4.  Link for local testing (`npm link` or `bun link`).
5.  Test using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) (`npx @modelcontextprotocol/inspector c7-mcp-server`).
6.  Make your changes in the `src/` directory and rebuild.

## License

[MIT](LICENSE)