Metadata-Version: 2.4
Name: scicon
Version: 0.1.0
Summary: Scientific Context Protocol.
Project-URL: Homepage, https://github.com/twinapse/scicon
Project-URL: Repository, https://github.com/twinapse/scicon
Project-URL: Issues, https://github.com/twinapse/scicon/issues
Author: Twinapse
License: MIT License
        
        Copyright (c) 2026 Mikel Elkano Ilintxeta
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: mcp>=1.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomlkit>=0.13
Provides-Extra: dev
Requires-Dist: isort==8.0.1; extra == 'dev'
Requires-Dist: pylint==4.0.5; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff==0.15.12; extra == 'dev'
Requires-Dist: yapf==0.43.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: mcp>=1.2; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pyyaml>=6.0; extra == 'test'
Requires-Dist: tomlkit>=0.13; extra == 'test'
Description-Content-Type: text/markdown

# Scientific Context Protocol

This repository is the official implementation of the Scientific Context Protocol.
The installable `scicon` Python package serves hand-authored SCP packages through an MCP interface.
A target research repository installs `scicon`, authors a structured `scp-package/` directory, and exposes that package to AI agents through `scicon serve`.

The server validates structured package files and serves grounded answers through MCP.

<!-- toc -->

- [Current status](#current-status)
- [Pipeline](#pipeline)
- [Install and run](#install-and-run)
- [Register in a target repo](#register-in-a-target-repo)
- [Example package](#example-package)
- [Documentation](#documentation)

## Current status

This repository is currently in its MVP phase.
This section is the source of truth for the repository's current features and limitations.

### Features

- Package schema objects and closed evidence/predicate vocabularies.
- Path resolution for `--package-dir`, `SCP_PACKAGE_DIR`, and `./scp-package`.
- A typed YAML loader for hand-authored package files.
- Validation for IDs, statuses, links, predicate legality, section references, and uncertainty.
- Pure query functions for claims, figures, datasets, methods, code, assumptions, related objects, and resources.
- A thin FastMCP adapter and CLI subcommands: `scicon init`, `scicon serve`, and `scicon validate`.

### Limitations

- Mining and conversion are mocked, so humans author the package directly.
- At serve time, the server reads package YAML, not raw papers, notebooks, datasets, or repository files.
- The repository does not implement automatic artifact mining or general conversion for arbitrary repositories.
- Controlled operations remain final-product scope: the current MCP interface does not execute commands, download data, or modify files.

## Pipeline

```text
scientific output (SCP input)
  -> scp-package/
  -> MCP interface
  -> grounded SCP answers
```

The scientific output is conceptual input for package authors.

## Install and run

Install from this repository in a Python 3.12 environment:

```bash
pip install -e .
```

Validate the shipped example package:

```bash
scicon validate --package-dir examples/scp-package
```

Run the MCP server over stdio:

```bash
scicon serve --package-dir examples/scp-package
```

## Register in a target repo

In a target repository, create a hand-authored `scp-package/` directory and run:

```bash
scicon init .
```

`scicon init` writes MCP registration files plus agent instructions, skills, and prompts that tell supported coding agents to query the `scp` MCP tools first.
The command is idempotent and preserves user content outside its managed markers.
It registers `scicon serve` with the relative `scp-package` path.
See [docs/init.md](docs/init.md) for generated files and [docs/mcp-server.md](docs/mcp-server.md) for manual MCP registration and path resolution.

## Example package

[`examples/scp-package`](examples/scp-package) is the template and fixture shipped with this repository.
It contains one small neuroscience-style package with claims, figures, datasets, methods, code artifacts, assumptions, related work, operation recipes, and typed provenance edges.

## Documentation

### Start here

- [docs/overview.md](docs/overview.md): Vision, final-product context, and trust model.
- [docs/concepts.md](docs/concepts.md): Short glossary.

### Author and validate SCP packages

- [docs/package-schema.md](docs/package-schema.md): Package files, objects, statuses, and predicate vocabulary.
- [docs/validation.md](docs/validation.md): Validation checks and report behavior.

### Bootstrap and serve SCP packages

- [docs/init.md](docs/init.md): Target-repo bootstrap, managed files, agent targeting, and refresh/uninstall behavior.
- [docs/mcp-server.md](docs/mcp-server.md): MCP install, registration, tools, resources, and path resolution.

### Contribute

- [CONTRIBUTING.md](CONTRIBUTING.md): Shared contributor policies, checks, and Git conventions.
- [docs/architecture.md](docs/architecture.md): Package layout, layer boundaries, serving model, and interface contract.
- [docs/protocol.md](docs/protocol.md): Final-protocol context and expansion rules.
- [docs/releasing.md](docs/releasing.md): Release automation, versioning, changelog, and PyPI sequencing.
- [docs/coding-agent-setup.md](docs/coding-agent-setup.md): Project-local coding-agent setup guidance.
