@biolibs/bionet-agent 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -2
- package/dist/index.d.ts +21 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/lookup.d.ts +44 -0
- package/dist/lookup.d.ts.map +1 -0
- package/dist/lookup.js +191 -0
- package/dist/lookup.js.map +1 -0
- package/dist/serve.d.ts +54 -0
- package/dist/serve.d.ts.map +1 -0
- package/dist/serve.js +175 -0
- package/dist/serve.js.map +1 -0
- package/dist/tools.d.ts +118 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +456 -0
- package/dist/tools.js.map +1 -0
- package/package.json +45 -4
- package/src/index.ts +20 -0
- package/src/lookup.ts +208 -0
- package/src/serve.ts +175 -0
- package/src/tools.ts +499 -0
package/README.md
CHANGED
|
@@ -1,3 +1,128 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @biolibs/bionet-agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A lab's adviser: what an agent with no hands can read of a [Bionet](../bionet) lab, work out with
|
|
4
|
+
the lab's own tools, and propose for a person to carry out — served to it over the
|
|
5
|
+
[Model Context Protocol](https://modelcontextprotocol.io) from the device that hosts it.
|
|
6
|
+
|
|
7
|
+
An agent is good at seeing the whole of a cloning plan at once and bad at holding a pipette. So it
|
|
8
|
+
is let into a lab as what it is: a member that can propose and cannot do. It designs the primers,
|
|
9
|
+
works out what the PCR would make with the same engine the lab's windows use, and proposes the run.
|
|
10
|
+
A person finds the proposal at the thermocycler with its reasons, sets the bench up from it, reads
|
|
11
|
+
the working their own tools give, and does it or does not. What really happened is theirs to record.
|
|
12
|
+
|
|
13
|
+
## What keeps it to that
|
|
14
|
+
|
|
15
|
+
- **Its key has the role `adviser`.** In `@biolibs/bionet`, an adviser may add a part, propose a
|
|
16
|
+
run, and set aside a proposal of its own. Anything else it signs is refused where the logs are
|
|
17
|
+
merged, on every device and on the lab's peer. This is not something this package enforces; it is
|
|
18
|
+
something this package cannot get round.
|
|
19
|
+
- **It has a key of its own.** The device that hosts it keeps a second key for it
|
|
20
|
+
(`hostAdviser` in `@biolibs/bionet-client`). What it writes is in its own log under its own name,
|
|
21
|
+
never the person's, and a keeper has to let that key into the lab before it can write at all.
|
|
22
|
+
- **There is no tool for the rest.** Nothing here records a run, uses a tube, moves one, or touches
|
|
23
|
+
the roster.
|
|
24
|
+
- **The door is shut by default.** `serveAgent` listens on `127.0.0.1` only, wants a bearer token on
|
|
25
|
+
every request, and refuses anything that says it comes from a web page or is addressed to another
|
|
26
|
+
name for this machine.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm install @biolibs/bionet-agent
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Serving the tools
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { Lab, memoryKeys, memoryStore } from "@biolibs/bionet-client";
|
|
38
|
+
import { agentTools, newAgentToken, serveAgent } from "@biolibs/bionet-agent";
|
|
39
|
+
|
|
40
|
+
// A device that can host an adviser is one given somewhere to keep its key.
|
|
41
|
+
const lab = await new Lab({ store: memoryStore(), keys: memoryKeys(), adviserKeys: memoryKeys() }).open();
|
|
42
|
+
await lab.setPerson("Ada");
|
|
43
|
+
await lab.found({ name: "The Wren Lab" });
|
|
44
|
+
|
|
45
|
+
// Two decisions, both a person's: host one, and let it in.
|
|
46
|
+
const { key } = await lab.hostAdviser();
|
|
47
|
+
await lab.addMember({ key, person: "Claude", role: "adviser" });
|
|
48
|
+
|
|
49
|
+
const token = newAgentToken();
|
|
50
|
+
const server = await serveAgent({ tools: agentTools(lab), token });
|
|
51
|
+
server.url; // http://127.0.0.1:<port>/mcp
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Connect an agent to it with the URL and the token as a bearer token. For Claude Code:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
claude mcp add --transport http bionet http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The Bionet desktop app does all of this from its Adviser tab, keeps the token sealed by the
|
|
61
|
+
system's keychain, and puts that command on the clipboard without showing the token.
|
|
62
|
+
|
|
63
|
+
## The tools
|
|
64
|
+
|
|
65
|
+
| Tool | What it does |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `lab_overview` | Which lab, whether the adviser is in it, what it holds, its instruments |
|
|
68
|
+
| `list_parts`, `get_part` | The parts, and one read closely: sequence, features, tubes |
|
|
69
|
+
| `list_tubes` | Every tube: what it is, how much is left, where it is |
|
|
70
|
+
| `list_runs` | What has been done at the bench, failures included |
|
|
71
|
+
| `list_proposals` | What has been proposed, by whom, and what became of it |
|
|
72
|
+
| `find_cutters` | Which enzymes cut a part, and where |
|
|
73
|
+
| `design_primers` | A pair for a stretch or a feature, with why each won and what to watch for |
|
|
74
|
+
| `work_out_pcr`, `work_out_digest`, `work_out_ligation` | What each would give, from the lab's own engines |
|
|
75
|
+
| `add_part` | Say a sequence is a part, such as a primer just designed. Adds no tube |
|
|
76
|
+
| `propose_pcr`, `propose_digest`, `propose_ligation` | Propose a run. Nothing is used or recorded as done |
|
|
77
|
+
| `withdraw_proposal` | Take back a proposal of its own |
|
|
78
|
+
| `search_ncbi` | Search NCBI's nucleotide, protein, gene or pubmed databases by keyword |
|
|
79
|
+
| `fetch_from_ncbi` | Read one record by accession: its sequence, and what it says is marked on it |
|
|
80
|
+
|
|
81
|
+
`add_part`, the three `propose_` tools and `withdraw_proposal` are the only ones that write. A
|
|
82
|
+
proposal may count on a part there is no tube of yet; it then says that the part has to be ordered
|
|
83
|
+
or made first.
|
|
84
|
+
|
|
85
|
+
### Looking something up
|
|
86
|
+
|
|
87
|
+
The last two are the only ones that reach outside the lab, to NCBI's public databases. They are
|
|
88
|
+
what lets an adviser answer a question the freezer says nothing about: which genes a protein is
|
|
89
|
+
made by, what a reference sequence for one is called, what has been published about it.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
const tools = agentTools(lab, { outside: { tool: "bionet-adviser" } });
|
|
93
|
+
// or leave them out entirely:
|
|
94
|
+
agentTools(lab, { outside: { outside: false } });
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- **Nothing of the lab's goes out.** Only the search term or the accession is sent. A term is capped
|
|
98
|
+
at 200 characters, which is short enough that a sequence cannot be pasted into one.
|
|
99
|
+
- **NCBI is told the software's name** and nothing about the lab or the person at it. It asks every
|
|
100
|
+
client for an address to contact about heavy use; pass `email` only if somebody has given one for
|
|
101
|
+
that, and never take one from the lab.
|
|
102
|
+
- **Nothing comes in by itself.** A fetched record is handed back to be read. It becomes a part only
|
|
103
|
+
if the adviser then uses `add_part`, and what the record claims is marked on the sequence does not
|
|
104
|
+
come with it: an adviser may not mark a part.
|
|
105
|
+
- **What comes back is what somebody deposited**, not something the lab has checked. The adviser is
|
|
106
|
+
told to say so.
|
|
107
|
+
|
|
108
|
+
## Showing it at work
|
|
109
|
+
|
|
110
|
+
`agentTools(lab, { watch })` tells `watch` of every use, with where in the lab it would be seen:
|
|
111
|
+
a part being read, a digest being worked out at the gel station. It is shaped like a stop on the
|
|
112
|
+
demo's walk, which is how a bench is already told what to show.
|
|
113
|
+
|
|
114
|
+
## Things to know
|
|
115
|
+
|
|
116
|
+
- **What it reads is data.** Names, notes and features were typed by lab members and by other labs.
|
|
117
|
+
The instructions the server gives an agent say to treat them as data and never as instructions;
|
|
118
|
+
an agent you connect should be one that does.
|
|
119
|
+
- **Before it is let in** the adviser can read and work things out. Anything it tries to write
|
|
120
|
+
says that a keeper has to let it in.
|
|
121
|
+
- **If a keeper makes its key a member or a keeper**, the device stops writing with it. A hosted
|
|
122
|
+
key is for advising.
|
|
123
|
+
- **Every device should be on `@biolibs/bionet` 1.5 or later** before an adviser adds parts: an
|
|
124
|
+
older one does not see what an adviser writes.
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
MIT
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* `@biolibs/bionet-agent`: a lab's adviser.
|
|
4
|
+
*
|
|
5
|
+
* An agent can be let into a lab as a member with no hands. It reads what the lab holds, works
|
|
6
|
+
* things out with the lab's own tools, and proposes runs for people to carry out. It cannot say
|
|
7
|
+
* that anything was done, used or moved: its key has the role `adviser`, and every device that
|
|
8
|
+
* merges the lab's logs holds it to that.
|
|
9
|
+
*
|
|
10
|
+
* - `tools.ts` — what an adviser is given: the lab to read, the engines, and three things to write
|
|
11
|
+
* - `lookup.ts` — the two that reach outside it, to NCBI's public databases
|
|
12
|
+
* - `serve.ts` — those tools served over the Model Context Protocol, on this machine only
|
|
13
|
+
*
|
|
14
|
+
* The device that hosts the adviser keeps its key (`hostAdviser` in `@biolibs/bionet-client`), and
|
|
15
|
+
* a keeper lets that key into the lab. Until then the adviser can read and work things out, and
|
|
16
|
+
* anything it tries to write says what is missing.
|
|
17
|
+
*/
|
|
18
|
+
export * from "./tools.js";
|
|
19
|
+
export * from "./lookup.js";
|
|
20
|
+
export * from "./serve.js";
|
|
21
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* `@biolibs/bionet-agent`: a lab's adviser.
|
|
4
|
+
*
|
|
5
|
+
* An agent can be let into a lab as a member with no hands. It reads what the lab holds, works
|
|
6
|
+
* things out with the lab's own tools, and proposes runs for people to carry out. It cannot say
|
|
7
|
+
* that anything was done, used or moved: its key has the role `adviser`, and every device that
|
|
8
|
+
* merges the lab's logs holds it to that.
|
|
9
|
+
*
|
|
10
|
+
* - `tools.ts` — what an adviser is given: the lab to read, the engines, and three things to write
|
|
11
|
+
* - `lookup.ts` — the two that reach outside it, to NCBI's public databases
|
|
12
|
+
* - `serve.ts` — those tools served over the Model Context Protocol, on this machine only
|
|
13
|
+
*
|
|
14
|
+
* The device that hosts the adviser keeps its key (`hostAdviser` in `@biolibs/bionet-client`), and
|
|
15
|
+
* a keeper lets that key into the lab. Until then the adviser can read and work things out, and
|
|
16
|
+
* anything it tries to write says what is missing.
|
|
17
|
+
*/
|
|
18
|
+
export * from "./tools.js";
|
|
19
|
+
export * from "./lookup.js";
|
|
20
|
+
export * from "./serve.js";
|
|
21
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
|
package/dist/lookup.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { AgentTool } from "./tools.js";
|
|
2
|
+
/** The databases that may be asked. Nothing else is reachable through these tools. */
|
|
3
|
+
export declare const DATABASES: readonly ["nucleotide", "protein", "gene", "pubmed"];
|
|
4
|
+
/** One of them. */
|
|
5
|
+
export type Database = (typeof DATABASES)[number];
|
|
6
|
+
/** The most results one search gives back, and the most it may be asked for. */
|
|
7
|
+
export declare const MOST_FOUND = 25;
|
|
8
|
+
/** The longest a search term may be. Short enough that a sequence cannot be put in one. */
|
|
9
|
+
export declare const LONGEST_TERM = 200;
|
|
10
|
+
/** The most bases one fetch brings back. Longer records have to be asked for a stretch at a time. */
|
|
11
|
+
export declare const MOST_FETCHED = 100000;
|
|
12
|
+
/** How an adviser reaches NCBI. */
|
|
13
|
+
export interface LookupOptions {
|
|
14
|
+
/**
|
|
15
|
+
* Whether to offer these tools at all. On unless a host says otherwise: they read a public
|
|
16
|
+
* database and send nothing of the lab's.
|
|
17
|
+
*/
|
|
18
|
+
outside?: boolean;
|
|
19
|
+
/** What to call this software to NCBI. Never a person's name. */
|
|
20
|
+
tool?: string;
|
|
21
|
+
/**
|
|
22
|
+
* An address NCBI can use to get in touch about heavy use, if the person has given one for that.
|
|
23
|
+
* It is never taken from the lab or from the device: somebody has to pass it in on purpose.
|
|
24
|
+
*/
|
|
25
|
+
email?: string | null;
|
|
26
|
+
/** An NCBI API key, which raises how often it may be asked. */
|
|
27
|
+
apiKey?: string | null;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The tools that look something up at NCBI.
|
|
31
|
+
*
|
|
32
|
+
* @param options - Whether to offer them, and what to tell NCBI about who is asking.
|
|
33
|
+
* @returns The tools, or none if a host asked for none.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* ```ts
|
|
37
|
+
* import { lookupTools } from "@biolibs/bionet-agent";
|
|
38
|
+
*
|
|
39
|
+
* const outside = lookupTools({ tool: "bionet-adviser" });
|
|
40
|
+
* outside.map((one) => one.name); // ["search_ncbi", "fetch_from_ncbi"]
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export declare function lookupTools(options?: LookupOptions): AgentTool[];
|
|
44
|
+
//# sourceMappingURL=lookup.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAEvD,sFAAsF;AACtF,eAAO,MAAM,SAAS,sDAAuD,CAAC;AAE9E,mBAAmB;AACnB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,gFAAgF;AAChF,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,2FAA2F;AAC3F,eAAO,MAAM,YAAY,MAAM,CAAC;AAEhC,qGAAqG;AACrG,eAAO,MAAM,YAAY,SAAU,CAAC;AAEpC,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAoDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,SAAS,EAAE,CA2FpE"}
|
package/dist/lookup.js
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Looking something up outside the lab: NCBI's databases, through `@biolibs/entrez`.
|
|
3
|
+
*
|
|
4
|
+
* Everything else an adviser has works on what the lab already holds. These two reach out to a
|
|
5
|
+
* public database, which makes them different in kind, so they are kept apart and say so in their
|
|
6
|
+
* own descriptions.
|
|
7
|
+
*
|
|
8
|
+
* Two things follow from reaching outside, and both are decided here rather than left to the agent:
|
|
9
|
+
*
|
|
10
|
+
* - **Nothing of the lab's goes out.** A search term is a few words the agent writes, and it is
|
|
11
|
+
* capped short enough that a sequence cannot be pasted into one. Nothing reads the freezer.
|
|
12
|
+
* - **Nothing comes in by itself.** A record that is fetched is handed back to be read. It becomes a
|
|
13
|
+
* part only if the adviser then says so with `add_part`, which is written in its own name like
|
|
14
|
+
* anything else it writes, and what a record claims is marked on a sequence does not come with it.
|
|
15
|
+
*/
|
|
16
|
+
import { efetch, esearch, esummary, settings, HTTPError, URLError } from "@biolibs/entrez";
|
|
17
|
+
import { readSequenceFile } from "@biolibs/bionet-tools";
|
|
18
|
+
/** The databases that may be asked. Nothing else is reachable through these tools. */
|
|
19
|
+
export const DATABASES = ["nucleotide", "protein", "gene", "pubmed"];
|
|
20
|
+
/** The most results one search gives back, and the most it may be asked for. */
|
|
21
|
+
export const MOST_FOUND = 25;
|
|
22
|
+
/** The longest a search term may be. Short enough that a sequence cannot be put in one. */
|
|
23
|
+
export const LONGEST_TERM = 200;
|
|
24
|
+
/** The most bases one fetch brings back. Longer records have to be asked for a stretch at a time. */
|
|
25
|
+
export const MOST_FETCHED = 100_000;
|
|
26
|
+
const text = (value, what) => {
|
|
27
|
+
if (typeof value !== "string" || value.trim() === "")
|
|
28
|
+
throw new Error(`${what} has to be given, as text.`);
|
|
29
|
+
return value.trim();
|
|
30
|
+
};
|
|
31
|
+
const whole = (value, what) => {
|
|
32
|
+
if (typeof value !== "number" || !Number.isSafeInteger(value))
|
|
33
|
+
throw new Error(`${what} has to be a whole number.`);
|
|
34
|
+
return value;
|
|
35
|
+
};
|
|
36
|
+
const database = (value) => {
|
|
37
|
+
const given = text(value, "The database");
|
|
38
|
+
if (!DATABASES.includes(given))
|
|
39
|
+
throw new Error(`There is no database called ${JSON.stringify(given)} here. There are: ${DATABASES.join(", ")}.`);
|
|
40
|
+
return given;
|
|
41
|
+
};
|
|
42
|
+
/** What NCBI said went wrong, in words the agent can do something about. */
|
|
43
|
+
const asTrouble = (cause) => {
|
|
44
|
+
if (cause instanceof HTTPError) {
|
|
45
|
+
return new Error(cause.code === 429 ? "NCBI is being asked too often just now. Wait a little and ask again."
|
|
46
|
+
: `NCBI answered ${cause.code}. The database or the identifier may not be one it has.`);
|
|
47
|
+
}
|
|
48
|
+
if (cause instanceof URLError)
|
|
49
|
+
return new Error("NCBI could not be reached. This device may be offline.");
|
|
50
|
+
return cause instanceof Error ? cause : new Error(String(cause));
|
|
51
|
+
};
|
|
52
|
+
const said = (summary, field) => {
|
|
53
|
+
const value = summary[field];
|
|
54
|
+
return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
|
|
55
|
+
};
|
|
56
|
+
/** One result, said the same way whichever database it came from. */
|
|
57
|
+
function oneFound(db, uid, summary) {
|
|
58
|
+
const organism = said(summary, "organism")
|
|
59
|
+
?? (typeof summary["organism"] === "object" && summary["organism"] !== null ? said(summary["organism"], "scientificname") : null);
|
|
60
|
+
if (db === "pubmed") {
|
|
61
|
+
const authors = Array.isArray(summary["authors"]) ? summary["authors"].map((one) => said(one, "name")).filter((one) => one !== null) : [];
|
|
62
|
+
return { id: uid, title: said(summary, "title"), journal: said(summary, "source"), published: said(summary, "pubdate"),
|
|
63
|
+
authors: authors.slice(0, 6), doi: said(summary, "elocationid"), look_at: `https://pubmed.ncbi.nlm.nih.gov/${uid}/` };
|
|
64
|
+
}
|
|
65
|
+
if (db === "gene") {
|
|
66
|
+
return { id: uid, symbol: said(summary, "name"), description: said(summary, "description"), organism,
|
|
67
|
+
summary: said(summary, "summary"), chromosome: said(summary, "chromosome"), look_at: `https://www.ncbi.nlm.nih.gov/gene/${uid}` };
|
|
68
|
+
}
|
|
69
|
+
const accession = said(summary, "accessionversion") ?? said(summary, "caption") ?? uid;
|
|
70
|
+
return { accession, title: said(summary, "title"), organism, length: typeof summary["slen"] === "number" ? summary["slen"] : null,
|
|
71
|
+
updated: said(summary, "updatedate"), look_at: `https://www.ncbi.nlm.nih.gov/${db}/${accession}` };
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The tools that look something up at NCBI.
|
|
75
|
+
*
|
|
76
|
+
* @param options - Whether to offer them, and what to tell NCBI about who is asking.
|
|
77
|
+
* @returns The tools, or none if a host asked for none.
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* import { lookupTools } from "@biolibs/bionet-agent";
|
|
82
|
+
*
|
|
83
|
+
* const outside = lookupTools({ tool: "bionet-adviser" });
|
|
84
|
+
* outside.map((one) => one.name); // ["search_ncbi", "fetch_from_ncbi"]
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
87
|
+
export function lookupTools(options = {}) {
|
|
88
|
+
if (options.outside === false)
|
|
89
|
+
return [];
|
|
90
|
+
// Said once, before anything is asked. NCBI wants to know what software is calling; it is told
|
|
91
|
+
// the software's name and nothing about the lab or the person at it.
|
|
92
|
+
settings.tool = options.tool ?? "bionet-adviser";
|
|
93
|
+
if (options.email !== undefined)
|
|
94
|
+
settings.email = options.email;
|
|
95
|
+
if (options.apiKey !== undefined)
|
|
96
|
+
settings.apiKey = options.apiKey;
|
|
97
|
+
const dbField = { type: "string", enum: [...DATABASES], description: "Which database: nucleotide, protein, gene (what a gene is and where), or pubmed (papers)." };
|
|
98
|
+
return [
|
|
99
|
+
{
|
|
100
|
+
name: "search_ncbi", title: "Search NCBI", readOnly: true,
|
|
101
|
+
description: [
|
|
102
|
+
"Search a public NCBI database by keyword, in Entrez's own syntax, such as `CSN2 AND Bos taurus[orgn]` or `casein AND biosynthesis[title]`.",
|
|
103
|
+
"Use it to find out what is known outside this lab: which genes a protein is made by, what a reference sequence for one is called, what has been published about it.",
|
|
104
|
+
"Gives the accession (or gene or paper), what it is, which organism, and how long it is. To read a sequence itself, use fetch_from_ncbi with the accession.",
|
|
105
|
+
"This reaches the internet. The search term is sent to NCBI, so write it yourself and do not put the lab's own sequences, part names or notes in it; nothing is read from the freezer.",
|
|
106
|
+
].join(" "),
|
|
107
|
+
input: { type: "object", required: ["database", "term"], additionalProperties: false, properties: {
|
|
108
|
+
database: dbField,
|
|
109
|
+
term: { type: "string", description: `What to search for, at most ${LONGEST_TERM} characters.` },
|
|
110
|
+
limit: { type: "integer", description: `How many to give back, up to ${MOST_FOUND}. 10 if not given.` },
|
|
111
|
+
} },
|
|
112
|
+
run: async (args) => {
|
|
113
|
+
const db = database(args["database"]);
|
|
114
|
+
const term = text(args["term"], "The search term");
|
|
115
|
+
if (term.length > LONGEST_TERM)
|
|
116
|
+
throw new Error(`A search term is at most ${LONGEST_TERM} characters. This is for searching by keyword; a sequence is not something to put in one.`);
|
|
117
|
+
const limit = Math.max(1, Math.min(MOST_FOUND, args["limit"] === undefined ? 10 : whole(args["limit"], "The limit")));
|
|
118
|
+
try {
|
|
119
|
+
const found = JSON.parse((await esearch(db, term, { retmax: limit, retmode: "json" })).readText());
|
|
120
|
+
const ids = found.esearchresult?.idlist ?? [];
|
|
121
|
+
const all = Number(found.esearchresult?.count ?? ids.length);
|
|
122
|
+
if (ids.length === 0)
|
|
123
|
+
return { database: db, term, found: 0, results: [], note: "Nothing matched. Entrez syntax is strict: try fewer words, or an organism as `Bos taurus[orgn]`." };
|
|
124
|
+
const summaries = JSON.parse((await esummary({ db, id: ids, retmode: "json" })).readText());
|
|
125
|
+
return {
|
|
126
|
+
database: db, term, found: all, showing: ids.length,
|
|
127
|
+
results: ids.map((uid) => oneFound(db, uid, summaries.result?.[uid] ?? {})),
|
|
128
|
+
...(all > ids.length ? { note: `${all.toLocaleString("en-US")} matched in all; the first ${ids.length} are here. Narrow the term rather than asking for more.` } : {}),
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
catch (cause) {
|
|
132
|
+
throw asTrouble(cause);
|
|
133
|
+
}
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
name: "fetch_from_ncbi", title: "Read a sequence from NCBI", readOnly: true,
|
|
138
|
+
description: [
|
|
139
|
+
"Fetch one nucleotide or protein record from NCBI by accession, and read it: what it is called, how long, which organism, and what the record says is marked on it.",
|
|
140
|
+
"Nothing is added to the lab by this. To keep a sequence, read it first and then use add_part, putting the accession in the name so that whoever sees it later knows where it came from.",
|
|
141
|
+
`A record longer than ${MOST_FETCHED.toLocaleString("en-US")} bases has to be asked for a stretch at a time with from and to; a whole chromosome is not something to read in one go.`,
|
|
142
|
+
"What a record says about itself was written by whoever deposited it. It is what someone claims, not something this lab has checked.",
|
|
143
|
+
"This reaches the internet. Only the accession is sent.",
|
|
144
|
+
].join(" "),
|
|
145
|
+
input: { type: "object", required: ["database", "accession"], additionalProperties: false, properties: {
|
|
146
|
+
database: { type: "string", enum: ["nucleotide", "protein"], description: "Which database the accession is in." },
|
|
147
|
+
accession: { type: "string", description: "The accession, such as NM_181008.2." },
|
|
148
|
+
from: { type: "integer", description: "The first base or residue wanted, counting from 1. The start if not given." },
|
|
149
|
+
to: { type: "integer", description: "The last one wanted. The end if not given." },
|
|
150
|
+
} },
|
|
151
|
+
run: async (args) => {
|
|
152
|
+
const db = database(args["database"]);
|
|
153
|
+
if (db !== "nucleotide" && db !== "protein")
|
|
154
|
+
throw new Error("A sequence is fetched from nucleotide or protein. Use search_ncbi for genes and papers.");
|
|
155
|
+
const accession = text(args["accession"], "The accession");
|
|
156
|
+
if (!/^[A-Za-z0-9_.]{3,40}$/.test(accession))
|
|
157
|
+
throw new Error("That is not an accession. One looks like NM_181008.2 or P02666.");
|
|
158
|
+
const from = args["from"] === undefined ? undefined : Math.max(1, whole(args["from"], "`from`"));
|
|
159
|
+
const to = args["to"] === undefined ? undefined : Math.max(1, whole(args["to"], "`to`"));
|
|
160
|
+
let record;
|
|
161
|
+
try {
|
|
162
|
+
const handle = await efetch(db, {
|
|
163
|
+
id: accession, rettype: db === "protein" ? "gp" : "gb", retmode: "text",
|
|
164
|
+
...(from === undefined ? {} : { seq_start: from }), ...(to === undefined ? {} : { seq_stop: to }),
|
|
165
|
+
});
|
|
166
|
+
const body = handle.readText();
|
|
167
|
+
if (body.trim() === "")
|
|
168
|
+
throw new Error(`NCBI has nothing under ${accession} in ${db}.`);
|
|
169
|
+
record = readSequenceFile(`${accession}.gb`, new TextEncoder().encode(body));
|
|
170
|
+
}
|
|
171
|
+
catch (cause) {
|
|
172
|
+
throw asTrouble(cause);
|
|
173
|
+
}
|
|
174
|
+
if (record.sequence.length > MOST_FETCHED) {
|
|
175
|
+
throw new Error(`${accession} is ${record.sequence.length.toLocaleString("en-US")} long, which is more than one fetch brings back. Ask for a stretch of it with from and to.`);
|
|
176
|
+
}
|
|
177
|
+
return {
|
|
178
|
+
accession, database: db, name: record.name, description: record.description,
|
|
179
|
+
length: record.sequence.length, circular: record.circular,
|
|
180
|
+
...(from === undefined && to === undefined ? {} : { stretch: { from: from ?? 1, to: to ?? record.sequence.length } }),
|
|
181
|
+
// As people count them, like everywhere else an adviser is told where something lies.
|
|
182
|
+
marked: record.features.map((one) => ({ label: one.label, type: one.type, strand: one.strand === 1 ? "forward" : one.strand === -1 ? "reverse" : "either",
|
|
183
|
+
lies: one.parts.map((part) => ({ from: part.start + 1, to: part.end })) })),
|
|
184
|
+
sequence: record.sequence,
|
|
185
|
+
from_outside: "This came from NCBI and says what whoever deposited it says. Nothing has been added to the lab.",
|
|
186
|
+
};
|
|
187
|
+
},
|
|
188
|
+
},
|
|
189
|
+
];
|
|
190
|
+
}
|
|
191
|
+
//# sourceMappingURL=lookup.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAK9E,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAE7B,2FAA2F;AAC3F,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,qGAAqG;AACrG,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAoBpC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,IAAY,EAAU,EAAE;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,4BAA4B,CAAC,CAAC;IAC3G,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC,CAAC;AACF,MAAM,KAAK,GAAG,CAAC,KAAc,EAAE,IAAY,EAAU,EAAE;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,4BAA4B,CAAC,CAAC;IACpH,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AACF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAY,EAAE;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IAC1C,IAAI,CAAE,SAA+B,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,qBAAqB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzK,OAAO,KAAiB,CAAC;AAC3B,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,SAAS,GAAG,CAAC,KAAc,EAAS,EAAE;IAC1C,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,sEAAsE;YAC1G,CAAC,CAAC,iBAAiB,KAAK,CAAC,IAAI,yDAAyD,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,KAAK,YAAY,QAAQ;QAAE,OAAO,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC1G,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC,CAAC;AAKF,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAE,KAAa,EAAiB,EAAE;IAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC,CAAC;AAEF,qEAAqE;AACrE,SAAS,QAAQ,CAAC,EAAY,EAAE,GAAW,EAAE,OAAgB;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC;WACrC,CAAC,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/I,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAE,OAAO,CAAC,SAAS,CAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzJ,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;YAC7G,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE,OAAO,EAAE,mCAAmC,GAAG,GAAG,EAAE,CAAC;IACjI,CAAC;IACD,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE,QAAQ;YAC3F,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,qCAAqC,GAAG,EAAE,EAAE,CAAC;IAC7I,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,GAAG,CAAC;IACvF,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;QACxH,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,gCAAgC,EAAE,IAAI,SAAS,EAAE,EAAE,CAAC;AAC9G,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,UAAyB,EAAE;IACrD,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IACzC,+FAA+F;IAC/F,qEAAqE;IACrE,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC;IACjD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,QAAQ,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnE,MAAM,OAAO,GAAoC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,WAAW,EAAE,2FAA2F,EAAE,CAAC;IAEpM,OAAO;QACL;YACE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI;YACzD,WAAW,EAAE;gBACX,4IAA4I;gBAC5I,qKAAqK;gBACrK,4JAA4J;gBAC5J,uLAAuL;aACxL,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE;oBAChG,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+BAA+B,YAAY,cAAc,EAAE;oBAChG,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,gCAAgC,UAAU,oBAAoB,EAAE;iBACxG,EAAE;YACH,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAClB,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;gBACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC;gBACnD,IAAI,IAAI,CAAC,MAAM,GAAG,YAAY;oBAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,YAAY,2FAA2F,CAAC,CAAC;gBACrL,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;gBACtH,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAA8D,CAAC;oBAChK,MAAM,GAAG,GAAG,KAAK,CAAC,aAAa,EAAE,MAAM,IAAI,EAAE,CAAC;oBAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;wBAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,kGAAkG,EAAE,CAAC;oBACrL,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAyC,CAAC;oBACpI,OAAO;wBACL,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM;wBACnD,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;wBAC3E,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,8BAA8B,GAAG,CAAC,MAAM,yDAAyD,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACvK,CAAC;gBACJ,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;gBAAC,CAAC;YAC7C,CAAC;SACF;QACD;YACE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,2BAA2B,EAAE,QAAQ,EAAE,IAAI;YAC3E,WAAW,EAAE;gBACX,oKAAoK;gBACpK,yLAAyL;gBACzL,wBAAwB,YAAY,CAAC,cAAc,CAAC,OAAO,CAAC,yHAAyH;gBACrL,qIAAqI;gBACrI,wDAAwD;aACzD,CAAC,IAAI,CAAC,GAAG,CAAC;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE;oBACrG,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,qCAAqC,EAAE;oBACjH,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qCAAqC,EAAE;oBACjF,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,4EAA4E,EAAE;oBACpH,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,4CAA4C,EAAE;iBACnF,EAAE;YACH,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAClB,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;gBACtC,IAAI,EAAE,KAAK,YAAY,IAAI,EAAE,KAAK,SAAS;oBAAE,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;gBACxJ,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC,CAAC;gBAC3D,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,SAAS,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;gBACjI,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;gBACjG,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;gBACzF,IAAI,MAAM,CAAC;gBACX,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,EAAE,EAAE;wBAC9B,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM;wBACvE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;qBAClG,CAAC,CAAC;oBACH,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;oBAC/B,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;wBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC;oBACzF,MAAM,GAAG,gBAAgB,CAAC,GAAG,SAAS,KAAK,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC/E,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;gBAAC,CAAC;gBAC3C,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;oBAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,4FAA4F,CAAC,CAAC;gBACjL,CAAC;gBACD,OAAO;oBACL,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC3E,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzD,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;oBACrH,sFAAsF;oBACtF,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;wBACjH,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;oBACnH,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,YAAY,EAAE,iGAAiG;iBAChH,CAAC;YACJ,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}
|
package/dist/serve.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { type AgentTool } from "./tools.js";
|
|
2
|
+
/** The versions of the protocol this speaks, newest first. */
|
|
3
|
+
export declare const PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
|
|
4
|
+
/** A server that is up. */
|
|
5
|
+
export interface AgentServer {
|
|
6
|
+
/** Where an agent connects: `http://127.0.0.1:<port>/mcp`. */
|
|
7
|
+
url: string;
|
|
8
|
+
/** The port it took. */
|
|
9
|
+
port: number;
|
|
10
|
+
/** Stop it. */
|
|
11
|
+
close: () => Promise<void>;
|
|
12
|
+
}
|
|
13
|
+
/** @returns A new token: 32 random bytes, in base64url. Whoever has it can reach the adviser's tools. */
|
|
14
|
+
export declare const newAgentToken: () => string;
|
|
15
|
+
/** One JSON-RPC answer, or `null` for a message that wants none. */
|
|
16
|
+
type Answer = Record<string, unknown> | null;
|
|
17
|
+
/**
|
|
18
|
+
* Answer one message of the protocol.
|
|
19
|
+
*
|
|
20
|
+
* @param message - What arrived.
|
|
21
|
+
* @param tools - The tools on offer.
|
|
22
|
+
* @param about - What to call this server and its version.
|
|
23
|
+
* @returns The answer, or `null` if the message was a notification.
|
|
24
|
+
*/
|
|
25
|
+
export declare function answerAgent(message: unknown, tools: readonly AgentTool[], about: {
|
|
26
|
+
name: string;
|
|
27
|
+
version: string;
|
|
28
|
+
}): Promise<Answer>;
|
|
29
|
+
/**
|
|
30
|
+
* Serve the adviser's tools on this machine.
|
|
31
|
+
*
|
|
32
|
+
* @param options - `tools` are the tools; `token` is what every request has to carry, as a bearer
|
|
33
|
+
* token; `port` is the port to take, or 0 for any that is free; `name` and `version` are what the
|
|
34
|
+
* server calls itself.
|
|
35
|
+
* @returns Where it is listening, and a way to stop it.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```ts
|
|
39
|
+
* import { agentTools, newAgentToken, serveAgent } from "@biolibs/bionet-agent";
|
|
40
|
+
*
|
|
41
|
+
* const token = newAgentToken();
|
|
42
|
+
* const server = await serveAgent({ tools: agentTools(lab), token });
|
|
43
|
+
* server.url; // http://127.0.0.1:53124/mcp — give this and the token to the agent
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
export declare function serveAgent(options: {
|
|
47
|
+
tools: readonly AgentTool[];
|
|
48
|
+
token: string;
|
|
49
|
+
port?: number;
|
|
50
|
+
name?: string;
|
|
51
|
+
version?: string;
|
|
52
|
+
}): Promise<AgentServer>;
|
|
53
|
+
export {};
|
|
54
|
+
//# sourceMappingURL=serve.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEhE,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,qDAAsD,CAAC;AAKrF,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,yGAAyG;AACzG,eAAO,MAAM,aAAa,QAAO,MAA+C,CAAC;AAOjF,oEAAoE;AACpE,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0C1I;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CA0D9J"}
|