The shared developer library

PaperCloak Tools

Shared plumbing. Deliberate tool access.

A shared Python foundation for model-provider configuration, read-only MCP tool access and reusable agent execution loops.

  • Developers building assisted workflows
  • Maintainers inspecting repositories
  • Teams sharing agent infrastructure

Why it exists

Tools supplies the repeatable plumbing behind a tool-assisted investigation while each consuming application owns its question, scope and output contract.

A tool-assisted model workflow needs a provider connection, defined tools, request execution and a useful result format. Rebuilding those pieces in every application makes maintenance harder and lets permissions or provider assumptions drift between otherwise similar workflows.

PaperCloak Tools keeps that machinery in a small Python library. Its first documented consumer is an ecosystem audit runner. Audit questions, repository lists and report schemas belong to that consumer. The library supplies the execution pattern; the application owns scope, configuration, review and the meaning of its output.

What it is designed to do

The capabilities, in detail.

Build the common agent loop once, with explicit tool boundaries, instead of copying provider and tool-management code into every project.

Configure compatible providers consistently

A provider registry describes OpenAI-compatible endpoints without copying connection logic into each consumer. Model identifiers and credentials come from configuration rather than assumptions embedded in a workflow. Providers with a different wire format need a compatible gateway or separate work; appearing in a registry does not prove that every current model or endpoint has been exercised.

Expose a deliberate read-only tool set

The documented MCP integration connects filesystem and Git servers while exposing an explicit read-only allowlist to the model. Write, commit and execution tools are excluded from the supplied schemas. This provides a concrete boundary beneath the prompt, while configured roots and the actual connected server still determine which information can be read.

Reuse the tool-calling loop

The agent loop sends messages and permitted tool schemas to a model, executes requested tools through connected servers and returns their results for the next step. Consumers reuse this sequence instead of duplicating orchestration code. A successful response remains source material to interpret, not an endorsement of the model's conclusion.

Keep output contracts with the application

A consumer can request structured JSON when it needs a predictable handoff. It defines the schema and must validate and review the result. Requesting structure does not establish factual accuracy or replace the product's acceptance criteria.

Manage connections as a bounded session

The documented usage starts MCP servers within an asynchronous lifecycle and closes them when the session ends. Filesystem and Git targets are supplied explicitly. This helps a consumer treat tool access as a scoped operation instead of an accidental permanent service, with setup, dependency and provider failures handled by the application using the library.

Concept diagram of PaperCloak Tools: Define the task, Connect allowed tools, Run the investigation, Validate the handoff.
Workflow concept, illustrated. Select the graphic to open it at full size.

From input to useful result

How the work moves through.

  1. Define the task

    The consuming application chooses its question, permitted targets and output expectations. Product-specific rules stay outside the shared agent library.

  2. Connect allowed tools

    Resolve provider configuration and start the required MCP servers for selected filesystem or repository roots using the read-only tool policy.

  3. Run the investigation

    Let the model request permitted tool calls and inspect their returned material. External provider use depends on the consumer's configuration and authorization.

  4. Validate the handoff

    Check the final text or structured data against the consumer's requirements, preserve useful source references and close the tool connections.

A concrete example

One foundation behind several repository questions

An internal audit application asks whether a repository's documentation matches its source. It supplies the repository root, an evidence-focused prompt and a result schema. Tools provides the provider connection and read-only inspection loop; the audit application decides which records to inspect and what counts as a supported finding.

Another consumer could ask a different maintenance question using the same foundation without inheriting that audit's prompts or report layout. Reuse belongs in connection and execution behavior. The application still owns interpretation, data exposure choices and any later action on the findings.

What comes out of the work

Results you can understand.

Reusable library interfaces

Provider resolution, tool connections and agent execution available to consuming Python applications.

Consumer-defined responses

Text or requested structured JSON shaped around a specific application's task.

A constrained inspection path

Read-only tool exposure that keeps source investigation separate from modification and release.

Built around

Principles that shape the product.

  • OpenAI-compatible provider configuration
  • Explicit read-only MCP tool allowlists
  • Reusable execution with consumer-owned prompts and schemas

Connected work

A clear role in the family.

  • The ecosystem audit runner is the initial documented consumer.
  • Intelligence owns a different structured-validation runtime; the two are separate foundations, not interchangeable applications.

Worth understanding

Questions and boundaries.

Is this a collection of end-user utilities?

No. PaperCloak Tools is a developer library. Its useful interface is reusable Python code, not a separate document editor, dashboard or consumer toolbox.

Can it edit or commit a repository?

Those operations are outside the documented default tool allowlist. Any future write-capable workflow needs an explicit permission design rather than inheriting authority from a prompt.

Does running it keep all data local?

Not necessarily. Tool servers run locally, but a configured remote model receives the supplied conversation and tool results. The consumer must choose appropriate providers and data boundaries.

Continue exploring

Related tools, distinct jobs.

Shared plumbing. Deliberate tool access.

Explore the workflow Explore all software