# Tool reference

JustClaw-It exposes 8 MCP tools. Parameter tables on this page come from the server's own `tools/list`, so they always match what your agent sees. Your client may prefix the names (Claude Code shows `mcp__justclaw-it__search_components`).

| tool | credits per call | plan |
| --- | --- | --- |
| `search_components` | 0 | All plans |
| `find_similar` | 0 | All plans |
| `list_categories` | 0 | All plans |
| `get_component` | 1 | All plans |
| `library_stats` | 0 | All plans |
| `list_licenses` | 0 | All plans |
| `get_component_bundle` | 3 | Pro |
| `compose_starter` | 10 | Pro |

Connecting, `initialize`, `tools/list` and reading the [MCP App view](/docs/mcp-app) resource never cost credits. Discovery tools are free but rate-limited ([limits](/docs/credits#search-limits)). A call refused before it runs (bad key, no credits, rate limit) is not charged; a pull refused by the fair-use cap and a Pro tool tried on a non-Pro key are refunded.

A typical agent loop is: `search_components` with a concrete query and a `license` filter, read the results, then `get_component` on the one that fits best.

## search_components

**Credits:** 0 per call. **Plan:** All plans.

Semantic search over the public library. Your query is embedded and matched against component descriptions; results are ranked by similarity blended with the quality score (see [Scores & ranking](/docs/scores)). Results carry metadata, scores, licence and a GitHub permalink, but no source code: pull the one you want with `get_component`.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `query` | string | yes |  |
| `limit` | integer | no | `8` |
| `category` | string | no |  |
| `min_composite` | number | no | `0.0` |
| `language` | string | no |  |
| `license` | string | no | `"any"` |
| `offset` | integer | no | `0` |
| `max_per_repo` | integer | no | `3` |

- `query`: a short, concrete description of the job and the stack, for example `"express jwt auth middleware"`.
- `limit`: results per page (default 8, at most 50).
- `category`: one function tag, from `list_categories`. Common ones: `ai`, `ui`, `auth`, `database`, `payments`, `pos`, `crm`, `voice`, `email`, `infra`, `integration`, `automation`, `analytics`, `files`, `realtime`, `scraping`, `dev-tools`, `testing`, `security`, `search`, `chat`, `cli`.
- `min_composite`: drop results whose composite score is below this (0 to 10).
- `language`: one of `c`, `cpp`, `csharp`, `dart`, `go`, `java`, `javascript`, `kotlin`, `php`, `python`, `ruby`, `rust`, `shell`, `sql`, `svelte`, `swift`, `typescript`, `vue`.
- `license`: `permissive` (MIT, BSD, Apache-2.0, ISC and similar), `commercial-safe` (permissive plus weak copyleft such as MPL-2.0), `open-source`, or `any` (the default). The public library never serves strong copyleft, so `open-source` and `any` both return permissive and weak-copyleft code. Use `permissive` when the code goes into a closed product.
- `offset`: paging. Pages stop after offset 450.
- `max_per_repo`: at most this many results from one source repository (0 = no cap).

Language, licence and minimum-score filters are applied inside the database query, so a filtered search still returns full pages.

### Example call

```json
{
  "name": "search_components",
  "arguments": {
    "query": "python stripe webhook signature verify",
    "limit": 5,
    "license": "permissive",
    "min_composite": 6
  }
}
```

### What it returns

`{"results": [...]}`. Each result has `id`, `name`, `description`, `repo`, `path`, `loc`, `language`, `tags`, `source_url` (GitHub permalink), `similarity`, `scores` (`completeness`, `code_quality`, `deployability`, `reusability`, `strategic_value`, `composite`), `license` (SPDX), `license_kind` (`permissive` or `weak-copyleft`) and `attribution` (`repo_url`, `license_spdx`, `resell_class`, `copyright_holder`, `copyleft_flag`, `text`). Some results also carry [`security_advisories`](/docs/security-advisories). A `null` composite means the component has not been scored yet, not that it scored badly.

## get_component

**Credits:** 1 per call. **Plan:** All plans.

Pulls one component: its full source, GitHub permalink, licence, dependencies and an attribution block. The returned source starts with an attribution header comment; keep it with the code. This is the call that spends a credit.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `id` | string | yes |  |

- `id`: the `id` from a search result.

Every call costs 1 credit, including a re-pull of a component you already fetched (a re-pull does not count twice against your plan's yearly fair-use cap) and a call with an id that is not in the public library, so use ids from search results. A pull refused by the fair-use cap is refunded.

### Example call

```json
{
  "name": "get_component",
  "arguments": { "id": "<id from search_components>" }
}
```

### What it returns

`id`, `name`, `description`, `repo`, `repo_url`, `source_url`, `language`, `function_tags`, `tech_stack` (includes the file path), `dependencies`, `license`, `license_kind`, `attribution` and `source_code` (starting with the attribution header), plus `security_advisories` when present. Scores are on the search result, not here. For weak-copyleft files the header also says that modifications to that file stay under its licence. Errors: `not available` (unknown or not in the public library), `pull_ceiling_exceeded` (yearly fair-use cap; more credits do not lift it).

## find_similar

**Credits:** 0 per call. **Plan:** All plans.

Components similar to a given component id. **On the public library this currently returns an empty list**: nearest-neighbour lookup is not yet available behind the licence gate. It costs nothing; use `search_components` with a description of the component instead.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `limit` | integer | no | `8` |

### Example call

```json
{
  "name": "find_similar",
  "arguments": { "id": "<component id>", "limit": 8 }
}
```

### What it returns

`{"results": []}` today; the same shape as `search_components` once enabled.

## list_categories

**Credits:** 0 per call. **Plan:** All plans.

The most-used function tags with their counts. These are the valid values for `search_components.category`.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `limit` | integer | no | `40` |

### Example call

```json
{
  "name": "list_categories",
  "arguments": { "limit": 40 }
}
```

### What it returns

`{"categories": [{"tag": "auth", "count": ...}, ...]}`, most used first.

## library_stats

**Credits:** 0 per call. **Plan:** All plans.

Live library counts (refreshed in the background about every 15 minutes).

### Parameters

No parameters.

### Example call

```json
{
  "name": "library_stats",
  "arguments": {}
}
```

### What it returns

`total_components`, `callable_components`, `categorised` and the licence mode. While the counts are being computed after a restart it returns `{"status": "warming up"}`; retry in a minute.

## list_licenses

**Credits:** 0 per call. **Plan:** All plans.

Every source repository in the library with its SPDX licence and copyright holder: a NOTICE file you can keep with a project. The same list is at [/licenses](/licenses).

### Parameters

No parameters.

### Example call

```json
{
  "name": "list_licenses",
  "arguments": {}
}
```

### What it returns

`{"licenses": [{"repo_url", "license_spdx", "copyright_holder", "components"}, ...]}`.

## get_component_bundle

**Credits:** 3 per call. **Plan:** Pro.

Pro only. One component plus the components it imports from its own repository, each with source and an attribution header, and a manifest of files, npm/pip packages and install commands. Use it when one file is not enough to run.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `component_id` | string | yes |  |

- `component_id`: the `id` from a search result.

On a non-Pro key the call is refused with `pro_required` and the credit is refunded, so trying it costs nothing. If no bundle can be built the credits are refunded.

### Example call

```json
{
  "name": "get_component_bundle",
  "arguments": { "component_id": "<id>" }
}
```

### What it returns

The components with source and headers, a manifest, and `credits_charged`.

## compose_starter

**Credits:** 10 per call. **Plan:** Pro.

Pro only. Describe what you are building and get a starter project assembled from 3 to 8 complementary library components: file tree, files with attribution headers, a README listing every source and licence, a NOTICE file and install commands. Expect to fix some glue: the components come from different repositories.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `prompt` | string | yes |  |
| `stack` | string | no |  |

- `prompt`: one paragraph on what you are building and the features it needs.
- `stack`: optional, for example `"nextjs"` or `"python fastapi"`.

Refused calls (non-Pro key, not enough credits, nothing matched) are refunded.

### Example call

```json
{
  "name": "compose_starter",
  "arguments": {
    "prompt": "SaaS dashboard with email login, Stripe subscriptions and transactional email",
    "stack": "nextjs"
  }
}
```

### What it returns

The starter (tree, files, README, NOTICE, install commands) and `credits_charged`.


## Errors

Tool errors come back as JSON text, for example `{"error": "pull_ceiling_exceeded", "message": "..."}`. Refusals before the tool runs (bad key, no credits, rate limits) come back as an MCP error with a readable message. The full list is in [Troubleshooting](/docs/troubleshooting).