{
  "markdown": "# Factsets\n\n|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Package | ![NPM Downloads](https://img.shields.io/npm/dm/factsets?style=flat) ![NPM Version](https://img.shields.io/npm/v/factsets?style=flat)                                                                                                                                                                                                                                                                                                                                       |\n| CI/CD   | [![Release](https://github.com/joshua-auchincloss/factsets/actions/workflows/release.yaml/badge.svg)](https://github.com/joshua-auchincloss/factsets/actions) [![Tests](https://github.com/joshua-auchincloss/factsets/actions/workflows/test.yaml/badge.svg)](https://github.com/joshua-auchincloss/factsets/actions) [![codecov](https://codecov.io/gh/joshua-auchincloss/factsets/graph/badge.svg?token=IL8AIPFCX9)](https://codecov.io/gh/joshua-auchincloss/factsets) |\n\nA self-maintaining knowledge base for AI agents, exposed via the\n[Model Context Protocol (MCP)](https://modelcontextprotocol.io). Manages **facts** (atomic knowledge), **resources**\n(cached external content), **skills** (procedural markdown), and **execution logs** (command history) using SQLite.\n\n## Features\n\n- **Persistent Context** - Knowledge survives across sessions\n- **Self-Maintaining** - Staleness detection with refresh instructions\n- **Tag-Based Organization** - Flexible categorization and retrieval\n- **Skill Documents** - Markdown files for procedural knowledge\n- **User Preferences** - Configurable output style and agent behavior\n- **MCP Protocol** - Standard interface for AI tool/prompt definitions\n\n## Installation\n\n```bash\nnpm install --global factsets\npnpm install --global factsets\nbun install --global factsets\n```\n\n## Quick Start\n\n### As MCP Server\n\nAdd to your MCP client configuration (Claude Desktop, GitHub Copilot, Cursor, etc.), using `bunx`, `npx` or `pnpm dlx` accordingly:\n\n```json\n{\n  \"mcpServers\": {\n    \"factsets\": {\n      \"command\": \"bunx\",\n      \"args\": [\"factsets\", \"mcp-server\"]\n    }\n  }\n}\n```\n\nOr run directly:\n\n```bash\nbunx factsets mcp-server\n```\n\n### First-Time Setup\n\nAfter adding Factsets to your MCP client, run the setup prompt to integrate it into your project:\n\n**In a supported IDE**: Type `/mcp.factsets.setup` in the chat to run the guided setup\n\n**In other clients**: Call the `get_setup_guide` tool or use the `setup` prompt\n\nThe setup guide will:\n\n- Analyze your project structure and establish baseline facts\n- Configure the skills directory for your AI client\n- Create or update `AGENTS.md` with Factsets instructions\n- Migrate any existing skills with Factsets integration\n- Register key configuration files as resources\n\nThis one-time setup ensures agents have full context on every future interaction.\n\n### CLI Commands\n\n```bash\n# Start MCP server (default command - auto-watches skill files and seeds starter content)\nbunx factsets [--database-url <path>] [--client <type>]\n\n# Explicit mcp-server command (same as above)\nbunx factsets mcp-server [--database-url <path>] [--client <type>]\n\n# Start without file watching\nbunx factsets --no-watch-skills\n\n# Start without seeding starter content\nbunx factsets --no-seed\n\n# Run file watcher standalone\nbunx factsets watch-files [--database-url <path>]\n\n# Run background maintenance worker\nbunx factsets worker [--database-url <path>]\n\n# Export database to JSON\nbunx factsets dump backup.json\n\n# Restore database from JSON\nbunx factsets restore backup.json\n```\n\nThe `--client` flag configures where skill files are stored (e.g., `github-copilot` -> `.github/prompts/skills/`). If you want to change clients / your skill directory, do so through your agent which will migrate skills for you.\n\nSee [Configuration Guide](docs/config.md) for all options.\n\n## Core Concepts\n\n| Concept            | Description                                                                      |\n| ------------------ | -------------------------------------------------------------------------------- |\n| **Facts**          | Atomic knowledge units (1-3 sentences), tagged and timestamped                   |\n| **Resources**      | External content (files, URLs, APIs) with cached snapshots and retrieval methods |\n| **Skills**         | Markdown documents for procedural knowledge, stored on filesystem                |\n| **Execution Logs** | Command history with success/failure tracking for skill validation               |\n| **Tags**           | Flexible categorization for all content types                                    |\n\n## MCP Tools\n\n### Facts\n\n| Tool                   | Description                              |\n| ---------------------- | ---------------------------------------- |\n| `submit_facts`         | Add facts with tags and source tracking  |\n| `search_facts`         | Query facts by tags, content, or filters |\n| `verify_facts`         | Mark facts as verified by ID             |\n| `verify_facts_by_tags` | Bulk verify facts by tags                |\n| `update_fact`          | Update fact content, metadata, or tags   |\n| `delete_facts`         | Remove facts by criteria                 |\n| `restore_facts`        | Restore soft-deleted facts               |\n\n### Resources\n\n| Tool                        | Description                               |\n| --------------------------- | ----------------------------------------- |\n| `add_resources`             | Register resources with retrieval methods |\n| `search_resources`          | Find resources by tags, type, or URI      |\n| `get_resources`             | Get resources by ID or URI with freshness |\n| `update_resource_snapshot`  | Update cached content for single resource |\n| `update_resource_snapshots` | Bulk update cached content                |\n| `update_resource`           | Update resource metadata (not content)    |\n| `delete_resources`          | Remove resources                          |\n| `restore_resources`         | Restore soft-deleted resources            |\n\n### Skills\n\n| Tool                   | Description                          |\n| ---------------------- | ------------------------------------ |\n| `create_skill`         | Create markdown skill document       |\n| `update_skill`         | Update skill metadata/references     |\n| `search_skills`        | Find skills by tags or query         |\n| `get_skills`           | Get skills by name with content      |\n| `link_skill`           | Link skill to facts/resources/skills |\n| `sync_skill`           | Sync skill after file edit           |\n| `delete_skills`        | Remove skills                        |\n| `get_dependency_graph` | Get skill dependency tree            |\n| `restore_skills`       | Restore soft-deleted skills          |\n\n### Execution Logs\n\n| Tool                    | Description                             |\n| ----------------------- | --------------------------------------- |\n| `submit_execution_logs` | Record command/test/build executions    |\n| `search_execution_logs` | Find executions by query, tags, success |\n| `get_execution_log`     | Get execution details by ID             |\n\n### Tags\n\n| Tool                | Description                 |\n| ------------------- | --------------------------- |\n| `create_tags`       | Create organizational tags  |\n| `list_tags`         | List tags with usage counts |\n| `update_tags`       | Update tag descriptions     |\n| `prune_orphan_tags` | Clean up unused orphan tags |\n\n### Configuration\n\n| Tool                | Description                             |\n| ------------------- | --------------------------------------- |\n| `get_config`        | Get a configuration value by key        |\n| `set_config`        | Set a configuration value               |\n| `delete_config`     | Delete a configuration value            |\n| `list_config`       | List all configuration with schema      |\n| `get_config_schema` | Get available options with descriptions |\n\n### User Preferences\n\n| Tool                    | Description                            |\n| ----------------------- | -------------------------------------- |\n| `get_preference_prompt` | Get natural language preference prompt |\n| `get_user_preferences`  | Get structured preference data         |\n| `infer_preference`      | Update preference from user behavior   |\n| `reset_preferences`     | Reset preferences to defaults          |\n\n### Maintenance\n\n| Tool                       | Description                           |\n| -------------------------- | ------------------------------------- |\n| `check_stale`              | Find stale resources and dependencies |\n| `mark_resources_refreshed` | Mark resources as current             |\n\n### Context & Guides\n\n| Tool                     | Description                                      |\n| ------------------------ | ------------------------------------------------ |\n| `get_knowledge_context`  | Build context from tags (facts/resources/skills) |\n| `build_skill_context`    | Get skill with formatted content and refs        |\n| `get_maintenance_report` | Generate staleness/maintenance report            |\n| `get_refresh_guide`      | Get instructions for refreshing a resource       |\n| `get_agent_guide`        | Get the agent workflow guide (call first)        |\n| `get_concept_guide`      | Get conceptual overview and design philosophy    |\n| `get_config_guide`       | Get configuration guide with all options         |\n\n## MCP Prompts\n\n| Prompt               | Description                                |\n| -------------------- | ------------------------------------------ |\n| `setup`              | Guided setup for new project integration   |\n| `user_preferences`   | Get user preferences for output formatting |\n| `knowledge_context`  | Build context from tags                    |\n| `recall_skill`       | Get skill with references                  |\n| `maintenance_report` | Staleness summary                          |\n| `refresh_guide`      | Instructions to refresh a resource         |\n| `agent_guide`        | Agent workflow guide (call first)          |\n| `concept`            | Conceptual overview and philosophy         |\n| `config`             | Configuration guide with all options       |\n\n## Documentation\n\n- [Configuration Guide](docs/config.md) - CLI flags, client setup, and skills directory\n- [Design Reference](docs/design.md) - Full API documentation\n- [Concept](docs/concept.md) - Philosophy and design rationale\n- [Agent Workflow](docs/facts-agent-flow.md) - How agents use Factsets\n\n## Development\n\n```bash\n# Run tests\nbun test\n\n# Run full e2e (tests + build + dry run)\nbun e2e\n\n# Build distribution\nbun dist\n\n# Format code\nbun format\n\n# Lint\nbun lint\n\n# Generate database migrations\nbun migrations\n\n# Inspect MCP server with inspector\nbun inspect\n```\n",
  "bytes": 11727,
  "sha": "cf9c2d07e61557c0b2e5ac7a752da04a89821be3bbcc26d821a0b8ef426cd9db",
  "repo_slug": "joshua-auchincloss/factsets",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_joshua_auchincloss_factsets_9d504b1d/readme"
}