# textgraph

textgraph turns a piece of text into a knowledge graph and answers
questions about that graph: what the main topics and clusters are,
which connections are missing, and what research questions or ideas
those gaps suggest. It can also create a graph in an InfraNodus
account, analyse an existing graph by name, and compare several texts
through their graphs.

This package is a clean-room rebuild, and a **labelled core subset**:
it covers 12 of the 22+ tools documented for the original InfraNodus
MCP server. The omitted tools are listed under "Scope" below.

## How it talks to the service

Every tool needs an InfraNodus API key:

```bash
export INFRANODUS_API_KEY="your key"
# Optional override (default: https://api.infranodus.com)
export INFRANODUS_API_URL="https://api.infranodus.com"
```

With no key set, every call fails with an error naming
`INFRANODUS_API_KEY`, before any request is made.

**Wire-format note:** the original project's README documents the
tools and their purposes, not the HTTP wire format. The endpoint
shape used here is a documented reconstruction: each tool POSTs its
JSON arguments to `{INFRANODUS_API_URL}/<tool name>` — the tool name
with underscores, exactly as listed — with
`Authorization: Bearer INFRANODUS_API_KEY`. Responses are parsed
tolerantly: JSON is returned as structured text, a non-JSON body is
returned as-is, and an upstream HTTP error is reported with its
status and a body excerpt.

Local validation, applied before any request: `analyze_text`
requires at least one of `text` or `url`;
`optimize_text_structure`'s `responseType` must be one of `response`,
`idea`, `question`, or `transcend`; and `overlap_between_texts` /
`difference_between_texts` require at least two texts.

## Install

```bash
npx @reneturcios/textgraph generate_content_gaps '{"text":"..."}'
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/textgraph
```

The container defaults to the MCP server. Pass CLI arguments to use
it as a CLI instead.

## CLI

The CLI mirrors the tools: one subcommand per tool, taking its
arguments as a single JSON object.

```bash
textgraph generate_knowledge_graph '{"text":"...","graphName":"notes"}'
textgraph analyze_existing_graph_by_name '{"graphName":"notes"}'
textgraph analyze_text '{"url":"https://example.com/article"}'
textgraph optimize_text_structure '{"text":"...","responseType":"idea"}'
textgraph overlap_between_texts '{"texts":["first","second"]}'
textgraph --version
```

Exit codes: `0` on success, `1` on an API or validation error (the
error names the problem), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/textgraph mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "textgraph": {
      "command": "npx",
      "args": ["-y", "@reneturcios/textgraph", "mcp"],
      "env": { "INFRANODUS_API_KEY": "your key" }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `generate_knowledge_graph` | `text` (required), `graphName` | Convert text into a knowledge graph: topics, concepts, relationships, clusters. |
| `analyze_existing_graph_by_name` | `graphName` (required) | Retrieve and analyze an existing graph from the account. |
| `analyze_text` | `text` and/or `url` (at least one required, validated locally) | Analyze a text or URL: topics, clusters, statements, graph structure. |
| `generate_content_gaps` | `text` (required) | Detect missing connections and underexplored topics in a text. |
| `generate_topical_clusters` | `text` (required), `generateTopicalSummaries` | Topics and keyword clusters from text. |
| `generate_contextual_hint` | `text` (required) | Topical overview of a text to augment LLM responses. |
| `generate_research_questions` | `text` (required) | Research questions bridging content gaps. |
| `generate_research_ideas` | `text` (required) | Research ideas based on content gaps. |
| `optimize_text_structure` | `text` (required), `responseType` (one of response / idea / question / transcend, validated locally) | Bias/coherence analysis. |
| `create_knowledge_graph` | `text` (required), `graphName`, `statements`, `categories` | Create a graph in the account from text and return its link. |
| `overlap_between_texts` | `texts` (array, at least 2, validated locally) | Similarities between texts via their graphs. |
| `difference_between_texts` | `texts` (array, at least 2, validated locally) | What's in the other texts but not the first. |

## Scope

Omitted from this core subset: `optimize_reasoning`,
`generate_responses_from_graph`, `develop_conceptual_bridges`,
`develop_latent_topics`, `develop_text_tool`,
`generate_ontology_graph`, `analyze_llm_results`,
`merged_graph_from_texts`, `analyze_google_search_results`,
`analyze_youtube_results`, and any tools beyond the fetched README
list. The summaries, ideas, and questions these tools return are
produced by the upstream InfraNodus service; this package reproduces
the tool surface and the request/response handling, not that
service's analysis quality.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.