# Tool reference

JustClaw-It exposes 10 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 |
| `check_component_security` | 0 | All plans |
| `library_stats` | 0 | All plans |
| `list_licenses` | 0 | All plans |
| `get_component_bundle` | 3 | Pro |
| `compose_starter` | 10 | Pro |
| `licence_report` | 0 | All plans |

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` |
| `exclude_vulnerable` | boolean | no | `false` |

- `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.

## check_component_security

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

Looks up published CVE/GHSA advisories for components (by id) or repositories (by name), from the same data as the [`security_advisories`](/docs/security-advisories) warning. Free; use it before you pull, and on code you pulled earlier.

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `component_ids` | array | null | no |  |
| `names` | array | null | no |  |
| `packages` | array | null | no |  |

- `component_ids`: up to 25 ids from `search_components` or `get_component`.
- `names`: up to 25 repositories as `owner/repo` or a GitHub URL; a bare repo name matches every owner's repository with that name.

Advisory data (OSV, refreshed weekly) covers 8,372 repositories today (520 with at least one advisory, 4,116 advisories with severity, summary and fixed versions). `none_known` means no advisory in our data, not that the code is safe.

### Example call

```json
{
  "name": "check_component_security",
  "arguments": { "component_ids": ["<id>"], "names": ["nestjs/nest"] }
}
```

### What it returns

`{"results": [...], "summary", "coverage", "note"}`. Each result has `input`, `kind`, `repo`, `status` (`advisories`, `none_known` or `not_found`) and, with advisories, `count` and `advisories` (`id` plus a GitHub Advisory Database or NVD `url`).

## 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: the alternatives and variants of a file you already found. It describes that component (name, description, tags) to the same licence-cleared search as `search_components`, so every neighbour has a licence and attribution, and the component itself is left out. It costs nothing. An unknown id, or one that is not in the public library, returns an empty list.

### 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": [...]}`, the same shape as `search_components`, most similar first.

## 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`.

## licence_report

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

Licence report for a project's dependencies from its lockfiles: licence, licence class and sellable flag per package. The `summary` format is free; `cyclonedx`, `spdx` and `notice` documents cost 5 credits each (refunded when nothing can be parsed). Signed-in callers only. See [Lockfile licence report](/docs/licence-report).

### Parameters

| parameter | type | required | default |
| --- | --- | --- | --- |
| `files` | array | yes |  |
| `format` | string | no | `"summary"` |
| `private_scopes` | array | no |  |


## 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).